diff --git a/.claude/CLAUDE.generated.adoc b/.claude/CLAUDE.generated.adoc new file mode 100644 index 00000000..ece4f046 --- /dev/null +++ b/.claude/CLAUDE.generated.adoc @@ -0,0 +1,302 @@ +== PanLL — AI Coordination Rules + +____ +*Auto-generated from `+coordination.k9+`* — do not edit directly. +Re-generate with: +`+deno run --allow-read --allow-write generate.js coordination.k9+` +Source of truth: `+coordination.k9+` in repository root. +____ + +=== Project + +Neurosymbolic IDE built on the Binary Star model — human (symbolic, +Panel-L) and machine (neural, Panel-N) orbiting a shared world state +(Panel-W). 106 panels, custom TEA runtime, Gossamer desktop backend. + +*Languages:* ReScript, Rust, Elixir, JavaScript *License:* MPL-2.0 +*Build system:* just *Runtime:* deno + +=== Build Commands + +[cols=",",options="header",] +|=== +|Command |Description +|`+just build+` |Full build (ReScript + CSS + bundle) +|`+just res+` |ReScript compile only +|`+just bundle+` |esbuild bundle +|`+just css+` |Build CSS +|`+just dev+` |Start dev server on port 8000 +|`+just test+` |Run test suite (979 tests, 41 suites) +|`+just coverage+` |Run tests with coverage +|`+just lint+` |Lint ReScript source +|`+just doctor+` |Run project health checks +|=== + +=== INVARIANTS — Do Not Violate + +These rules are non-negotiable. Violating them will break the project or +contradict deliberate architectural decisions. + +==== [CRITICAL] custom-tea-runtime + +*Rule:* The custom TEA runtime in src/tea/ (18 modules) must NEVER be +replaced with rescript-tea or any other library + +*Why:* rescript-tea was deliberately evaluated and rejected. The custom +TEA runtime handles PanLL-specific needs: Anti-Crash circuit breaking, +Vexometer cognitive load adaptation, OrbitalSync multi-panel state +coherence, and panel lifecycle management. It is not legacy — it is the +architecture. + +==== [CRITICAL] no-typescript + +*Rule:* Do not introduce TypeScript files — ReScript is the frontend +language + +*Why:* ReScript provides better type safety with less overhead. This is +a deliberate, ecosystem-wide decision. + +==== [CRITICAL] no-tauri + +*Rule:* Do not introduce Tauri references or dependencies — Gossamer is +the desktop backend + +*Why:* PanLL was migrated FROM Tauri 2.0 TO Gossamer. This migration is +complete and intentional. + +==== [CRITICAL] tea-pattern-only + +*Rule:* All state management uses TEA (Model -> Msg -> Update -> View) — +no MVC, Redux, hooks, or other patterns + +*Why:* TEA is foundational to PanLL’s architecture. Model.res holds all +state, Msg.res defines all messages, Update.res is the state transition +kernel. + +==== [CRITICAL] all-state-in-model + +*Rule:* ALL application state lives in Model.model — no global mutable +state, no module-level state, no window.* state + +*Why:* TEA requires single state tree. Anti-Crash and OrbitalSync depend +on this invariant for correctness. + +==== [CRITICAL] no-npm-bun + +*Rule:* No npm, Bun, pnpm, or yarn — Deno is the orchestrator + +*Why:* npm is used ONLY for the ReScript compiler (which requires it). +All other tooling uses Deno. Do not add npm dependencies. + +==== [CRITICAL] anticrash-validates-all + +*Rule:* Anti-Crash circuit breaker validates ALL neural tokens before +symbolic execution — never bypass this + +*Why:* Safety-critical: prevents untrusted neural output from corrupting +symbolic state. The validation path exists for a reason. + +==== [HIGH] panels-not-panes + +*Rule:* UI elements are called '`panels`', NEVER '`panes`', '`tabs`', or +'`windows`' + +*Why:* PanLL naming convention — '`panels`' is the correct term +everywhere in code, docs, and communication + +==== [CRITICAL] no-bulk-panel-deletion + +*Rule:* Do not delete more than 2 panel files in a single operation +without explicit user approval + +*Why:* 106 panels have complex interdependencies. Bulk deletion can +cascade and break OrbitalSync. + +==== [HIGH] gossamer-bridge-pattern + +*Rule:* Gossamer commands in src/commands/ are invoke wrappers only — do +not put business logic there + +*Why:* Business logic belongs in Update.res. Commands are thin bridges +to the Gossamer backend. + +==== [CRITICAL] binary-star-model + +*Rule:* The Binary Star architecture (Panel-L symbolic + Panel-N neural ++ Panel-W world) is deliberate — do not flatten into a single panel type + +*Why:* The three panel types serve fundamentally different roles. This +is the core design of PanLL. + +==== [CRITICAL] rescript-core-team + +*Rule:* The project owner is on the ReScript core team — do not suggest +migrating away from ReScript + +*Why:* ReScript is not a temporary choice. The owner contributes to +ReScript itself. + +=== Protected Files and Directories + +Do NOT delete, reorganise, or replace these without explicit user +approval: + +[width="100%",cols="43%,57%",options="header",] +|=== +|Path |Reason +|`+src/tea/+` |Custom TEA runtime — 18 modules. NEVER replace with +rescript-tea. + +|`+src/Model.res+` |Single state tree — all application state lives here + +|`+src/Msg.res+` |Message type definitions — the TEA message catalogue + +|`+src/Update.res+` |State transition kernel — ~7500 lines, the heart of +PanLL + +|`+src/View.res+` |Root view renderer + +|`+src/App.res+` |Application entry point + +|`+src/core/+` |Core engines — AntiCrash, OrbitalSync, Contractiles, +TypeLLEngine, VabEngine + +|`+src/components/+` |106 panel views — do not bulk-delete + +|`+src/commands/+` |Gossamer bridge commands — thin wrappers only + +|`+src/modules/+` |Module registry + TypeLLService — cross-panel type +intelligence + +|`+src-gossamer/+` |Rust backend (WebKitGTK) — Gossamer desktop +integration + +|`+beam/+` |Elixir/BEAM API layer + +|`+tests/+` |979 tests, 41 suites — never delete tests + +|`+.machine_readable/+` |Canonical location for A2ML state files — MUST +stay here + +|`+coordination.k9+` |This file — source of truth for AI coordination +|=== + +=== Architecture Decisions (Deliberate) + +These choices may look unusual but are intentional: + +==== gossamer-not-tauri + +*Decision:* Gossamer (Zig + WebKitGTK) is the desktop backend — +migration from Tauri 2.0 is complete + +*Why:* Gossamer is the hyperpolymath desktop runtime. Tauri was used +previously but replaced. + +*Rejected alternatives:* Tauri 2.0, Electron, native GTK + +==== custom-tea-not-rescript-tea + +*Decision:* Custom TEA runtime (src/tea/, 18 modules) instead of the +rescript-tea library + +*Why:* PanLL needs Anti-Crash integration, OrbitalSync, Vexometer hooks, +and panel lifecycle — none available in rescript-tea + +*Rejected alternatives:* rescript-tea, Redux, MobX, React hooks pattern + +==== deno-npm-hybrid + +*Decision:* Deno orchestrates everything, but npm is used solely for the +ReScript compiler + +*Why:* ReScript compiler requires npm — this is the ONLY permitted npm +usage. Do not extend npm’s role. + +==== binary-star + +*Decision:* Four panel types: Panel-A (ambient/substrate), Panel-L +(logic/symbolic), Panel-N (neural/machine), Panel-W (world/shared) + +*Why:* L + N orbit W in the Binary Star core (clear separation of human +reasoning, machine inference, and shared world state); Panel-A surrounds +as ambient substrate for persistent context and ergonomic support. + +==== vexometer-cognitive-load + +*Decision:* Vexometer monitors operator stress and adapts UI detail +density + +*Why:* HTI (Human-Tool Interaction) principle — the IDE adapts to the +human, not vice versa + +==== anticrash-circuit-breaker + +*Decision:* Anti-Crash validates all neural tokens before they enter the +symbolic pipeline + +*Why:* Safety boundary between neural and symbolic systems — prevents +hallucinated code from corrupting state + +=== Do NOT Create + +These files, patterns, or systems must NOT be introduced: + +* ****/*.ts** — TypeScript is banned — use ReScript +* *Dockerfile* — Use Containerfile (Podman, not Docker) +* ****/*.py** — Python is banned — use ReScript, Rust, or Elixir +* *A replacement TEA runtime or state management library* — src/tea/ is +the TEA runtime — it is custom, deliberate, and must not be replaced +* *REST API endpoints parallel to existing Groove protocol endpoints* — +Groove is the inter-service communication protocol — do not create REST +alternatives +* *A new panel type beyond Panel-L, Panel-N, Panel-W* — Binary Star +model has exactly three types — adding more would break OrbitalSync +* *Direct Tauri imports or tauri.conf.json* — Tauri migration to +Gossamer is complete — do not reintroduce + +=== Terminology + +Use the correct terms for this project: + +* Say *"`panels`"*, NOT "`panes`", "`tabs`", "`windows`" +** PanLL UI elements are always called panels — this is enforced +everywhere +* Say *"`Binary Star`"*, NOT "`dual-pane`", "`split-view`", +"`two-panel`" +** The architectural model is Binary Star (Panel-L + Panel-N orbiting +Panel-W) +* Say *"`Anti-Crash`"*, NOT "`validator`", "`sanitizer`", "`filter`" +** The neural token validation system is called Anti-Crash +* Say *"`Vexometer`"*, NOT "`stress meter`", "`load indicator`", +"`fatigue tracker`" +** The cognitive load monitoring system is called Vexometer +* Say *"`OrbitalSync`"*, NOT "`state sync`", "`panel sync`", "`sync +engine`" +** The multi-panel state coherence system is called OrbitalSync + +=== Port Assignments + +[cols=",",options="header",] +|=== +|Service |Port +|dev-server |8000 +|echidna |9000 +|verisim |8080 +|boj-server |7700 +|typell |7800 +|=== + +=== Ecosystem Context + +*Depends on:* - *gossamer* — Desktop backend runtime (Zig + WebKitGTK) - +*verisim* — Persistent storage layer - *typell* — Type intelligence +engine — cross-panel type checking - *boj-server* — MCP server — all +external tool integration + +*Consumed by:* - *idaptik* — Uses PanLL as level editor for game content + +*Related projects:* - *echidna* — Proof engine — formal verification +integration - *hypatia* — Neurosymbolic CI/CD scanning - *panic-attack* +— Security scanning tool - *gitbot-fleet* — Bot orchestration (rhodibot, +echidnabot, etc.) - *proven* — Formally verified alternatives library diff --git a/.claude/CLAUDE.generated.md b/.claude/CLAUDE.generated.md deleted file mode 100644 index ca18f561..00000000 --- a/.claude/CLAUDE.generated.md +++ /dev/null @@ -1,230 +0,0 @@ - - - - -# PanLL — AI Coordination Rules - -> **Auto-generated from `coordination.k9`** — do not edit directly. -> Re-generate with: `deno run --allow-read --allow-write generate.js coordination.k9` -> Source of truth: `coordination.k9` in repository root. - -## Project - -Neurosymbolic IDE built on the Binary Star model — human (symbolic, Panel-L) and machine (neural, Panel-N) orbiting a shared world state (Panel-W). 106 panels, custom TEA runtime, Gossamer desktop backend. - -**Languages:** ReScript, Rust, Elixir, JavaScript -**License:** MPL-2.0 -**Build system:** just -**Runtime:** deno - -## Build Commands - -| Command | Description | -|---------|-------------| -| `just build` | Full build (ReScript + CSS + bundle) | -| `just res` | ReScript compile only | -| `just bundle` | esbuild bundle | -| `just css` | Build CSS | -| `just dev` | Start dev server on port 8000 | -| `just test` | Run test suite (979 tests, 41 suites) | -| `just coverage` | Run tests with coverage | -| `just lint` | Lint ReScript source | -| `just doctor` | Run project health checks | - -## INVARIANTS — Do Not Violate - -These rules are non-negotiable. Violating them will break the project -or contradict deliberate architectural decisions. - -### [CRITICAL] custom-tea-runtime - -**Rule:** The custom TEA runtime in src/tea/ (18 modules) must NEVER be replaced with rescript-tea or any other library - -**Why:** rescript-tea was deliberately evaluated and rejected. The custom TEA runtime handles PanLL-specific needs: Anti-Crash circuit breaking, Vexometer cognitive load adaptation, OrbitalSync multi-panel state coherence, and panel lifecycle management. It is not legacy — it is the architecture. - -### [CRITICAL] no-typescript - -**Rule:** Do not introduce TypeScript files — ReScript is the frontend language - -**Why:** ReScript provides better type safety with less overhead. This is a deliberate, ecosystem-wide decision. - -### [CRITICAL] no-tauri - -**Rule:** Do not introduce Tauri references or dependencies — Gossamer is the desktop backend - -**Why:** PanLL was migrated FROM Tauri 2.0 TO Gossamer. This migration is complete and intentional. - -### [CRITICAL] tea-pattern-only - -**Rule:** All state management uses TEA (Model -> Msg -> Update -> View) — no MVC, Redux, hooks, or other patterns - -**Why:** TEA is foundational to PanLL's architecture. Model.res holds all state, Msg.res defines all messages, Update.res is the state transition kernel. - -### [CRITICAL] all-state-in-model - -**Rule:** ALL application state lives in Model.model — no global mutable state, no module-level state, no window.* state - -**Why:** TEA requires single state tree. Anti-Crash and OrbitalSync depend on this invariant for correctness. - -### [CRITICAL] no-npm-bun - -**Rule:** No npm, Bun, pnpm, or yarn — Deno is the orchestrator - -**Why:** npm is used ONLY for the ReScript compiler (which requires it). All other tooling uses Deno. Do not add npm dependencies. - -### [CRITICAL] anticrash-validates-all - -**Rule:** Anti-Crash circuit breaker validates ALL neural tokens before symbolic execution — never bypass this - -**Why:** Safety-critical: prevents untrusted neural output from corrupting symbolic state. The validation path exists for a reason. - -### [HIGH] panels-not-panes - -**Rule:** UI elements are called 'panels', NEVER 'panes', 'tabs', or 'windows' - -**Why:** PanLL naming convention — 'panels' is the correct term everywhere in code, docs, and communication - -### [CRITICAL] no-bulk-panel-deletion - -**Rule:** Do not delete more than 2 panel files in a single operation without explicit user approval - -**Why:** 106 panels have complex interdependencies. Bulk deletion can cascade and break OrbitalSync. - -### [HIGH] gossamer-bridge-pattern - -**Rule:** Gossamer commands in src/commands/ are invoke wrappers only — do not put business logic there - -**Why:** Business logic belongs in Update.res. Commands are thin bridges to the Gossamer backend. - -### [CRITICAL] binary-star-model - -**Rule:** The Binary Star architecture (Panel-L symbolic + Panel-N neural + Panel-W world) is deliberate — do not flatten into a single panel type - -**Why:** The three panel types serve fundamentally different roles. This is the core design of PanLL. - -### [CRITICAL] rescript-core-team - -**Rule:** The project owner is on the ReScript core team — do not suggest migrating away from ReScript - -**Why:** ReScript is not a temporary choice. The owner contributes to ReScript itself. - -## Protected Files and Directories - -Do NOT delete, reorganise, or replace these without explicit user approval: - -| Path | Reason | -|------|--------| -| `src/tea/` | Custom TEA runtime — 18 modules. NEVER replace with rescript-tea. | -| `src/Model.res` | Single state tree — all application state lives here | -| `src/Msg.res` | Message type definitions — the TEA message catalogue | -| `src/Update.res` | State transition kernel — ~7500 lines, the heart of PanLL | -| `src/View.res` | Root view renderer | -| `src/App.res` | Application entry point | -| `src/core/` | Core engines — AntiCrash, OrbitalSync, Contractiles, TypeLLEngine, VabEngine | -| `src/components/` | 106 panel views — do not bulk-delete | -| `src/commands/` | Gossamer bridge commands — thin wrappers only | -| `src/modules/` | Module registry + TypeLLService — cross-panel type intelligence | -| `src-gossamer/` | Rust backend (WebKitGTK) — Gossamer desktop integration | -| `beam/` | Elixir/BEAM API layer | -| `tests/` | 979 tests, 41 suites — never delete tests | -| `.machine_readable/` | Canonical location for A2ML state files — MUST stay here | -| `coordination.k9` | This file — source of truth for AI coordination | - -## Architecture Decisions (Deliberate) - -These choices may look unusual but are intentional: - -### gossamer-not-tauri - -**Decision:** Gossamer (Zig + WebKitGTK) is the desktop backend — migration from Tauri 2.0 is complete - -**Why:** Gossamer is the hyperpolymath desktop runtime. Tauri was used previously but replaced. - -**Rejected alternatives:** Tauri 2.0, Electron, native GTK - -### custom-tea-not-rescript-tea - -**Decision:** Custom TEA runtime (src/tea/, 18 modules) instead of the rescript-tea library - -**Why:** PanLL needs Anti-Crash integration, OrbitalSync, Vexometer hooks, and panel lifecycle — none available in rescript-tea - -**Rejected alternatives:** rescript-tea, Redux, MobX, React hooks pattern - -### deno-npm-hybrid - -**Decision:** Deno orchestrates everything, but npm is used solely for the ReScript compiler - -**Why:** ReScript compiler requires npm — this is the ONLY permitted npm usage. Do not extend npm's role. - -### binary-star - -**Decision:** Four panel types: Panel-A (ambient/substrate), Panel-L (logic/symbolic), Panel-N (neural/machine), Panel-W (world/shared) - -**Why:** L + N orbit W in the Binary Star core (clear separation of human reasoning, machine inference, and shared world state); Panel-A surrounds as ambient substrate for persistent context and ergonomic support. - -### vexometer-cognitive-load - -**Decision:** Vexometer monitors operator stress and adapts UI detail density - -**Why:** HTI (Human-Tool Interaction) principle — the IDE adapts to the human, not vice versa - -### anticrash-circuit-breaker - -**Decision:** Anti-Crash validates all neural tokens before they enter the symbolic pipeline - -**Why:** Safety boundary between neural and symbolic systems — prevents hallucinated code from corrupting state - -## Do NOT Create - -These files, patterns, or systems must NOT be introduced: - -- ****/*.ts** — TypeScript is banned — use ReScript -- **Dockerfile** — Use Containerfile (Podman, not Docker) -- ****/*.py** — Python is banned — use ReScript, Rust, or Elixir -- **A replacement TEA runtime or state management library** — src/tea/ is the TEA runtime — it is custom, deliberate, and must not be replaced -- **REST API endpoints parallel to existing Groove protocol endpoints** — Groove is the inter-service communication protocol — do not create REST alternatives -- **A new panel type beyond Panel-L, Panel-N, Panel-W** — Binary Star model has exactly three types — adding more would break OrbitalSync -- **Direct Tauri imports or tauri.conf.json** — Tauri migration to Gossamer is complete — do not reintroduce - -## Terminology - -Use the correct terms for this project: - -- Say **"panels"**, NOT "panes", "tabs", "windows" - - PanLL UI elements are always called panels — this is enforced everywhere -- Say **"Binary Star"**, NOT "dual-pane", "split-view", "two-panel" - - The architectural model is Binary Star (Panel-L + Panel-N orbiting Panel-W) -- Say **"Anti-Crash"**, NOT "validator", "sanitizer", "filter" - - The neural token validation system is called Anti-Crash -- Say **"Vexometer"**, NOT "stress meter", "load indicator", "fatigue tracker" - - The cognitive load monitoring system is called Vexometer -- Say **"OrbitalSync"**, NOT "state sync", "panel sync", "sync engine" - - The multi-panel state coherence system is called OrbitalSync - -## Port Assignments - -| Service | Port | -|---------|------| -| dev-server | 8000 | -| echidna | 9000 | -| verisim | 8080 | -| boj-server | 7700 | -| typell | 7800 | - -## Ecosystem Context - -**Depends on:** -- **gossamer** — Desktop backend runtime (Zig + WebKitGTK) -- **verisim** — Persistent storage layer -- **typell** — Type intelligence engine — cross-panel type checking -- **boj-server** — MCP server — all external tool integration - -**Consumed by:** -- **idaptik** — Uses PanLL as level editor for game content - -**Related projects:** -- **echidna** — Proof engine — formal verification integration -- **hypatia** — Neurosymbolic CI/CD scanning -- **panic-attack** — Security scanning tool -- **gitbot-fleet** — Bot orchestration (rhodibot, echidnabot, etc.) -- **proven** — Formally verified alternatives library diff --git a/.junie/guidelines.adoc b/.junie/guidelines.adoc new file mode 100644 index 00000000..0c598dcb --- /dev/null +++ b/.junie/guidelines.adoc @@ -0,0 +1,306 @@ +== PanLL — AI Coordination Rules + +____ +*Auto-generated from `+coordination.k9+`* — do not edit directly. +Re-generate with: +`+deno run --allow-read --allow-write generate.js coordination.k9+` +Source of truth: `+coordination.k9+` in repository root. +____ + +=== Project + +Neurosymbolic IDE built on the Binary Star model — human (symbolic, +Panel-L) and machine (neural, Panel-N) orbiting a shared world state +(Panel-W). 106 panels, custom TEA runtime, Gossamer desktop backend. + +*Languages:* ReScript, Rust, Elixir, JavaScript *License:* MPL-2.0 +*Build system:* just *Runtime:* deno + +=== Build Commands + +[cols=",",options="header",] +|=== +|Command |Description +|`+just build+` |Full build (ReScript + CSS + bundle) +|`+just res+` |ReScript compile only +|`+just bundle+` |esbuild bundle +|`+just css+` |Build CSS +|`+just dev+` |Start dev server on port 8000 +|`+just test+` |Run test suite (979 tests, 41 suites) +|`+just coverage+` |Run tests with coverage +|`+just lint+` |Lint ReScript source +|`+just doctor+` |Run project health checks +|=== + +=== INVARIANTS — Do Not Violate + +These rules are non-negotiable. Violating them will break the project or +contradict deliberate architectural decisions. + +==== [CRITICAL] custom-tea-runtime + +*Rule:* The custom TEA runtime in src/tea/ (18 modules) must NEVER be +replaced with rescript-tea or any other library + +*Why:* rescript-tea was deliberately evaluated and rejected. The custom +TEA runtime handles PanLL-specific needs: Anti-Crash circuit breaking, +Vexometer cognitive load adaptation, OrbitalSync multi-panel state +coherence, and panel lifecycle management. It is not legacy — it is the +architecture. + +==== [CRITICAL] no-typescript + +*Rule:* Do not introduce TypeScript files — ReScript is the frontend +language + +*Why:* ReScript provides better type safety with less overhead. This is +a deliberate, ecosystem-wide decision. + +==== [CRITICAL] no-tauri + +*Rule:* Do not introduce Tauri references or dependencies — Gossamer is +the desktop backend + +*Why:* PanLL was migrated FROM Tauri 2.0 TO Gossamer. This migration is +complete and intentional. + +==== [CRITICAL] tea-pattern-only + +*Rule:* All state management uses TEA (Model -> Msg -> Update -> View) — +no MVC, Redux, hooks, or other patterns + +*Why:* TEA is foundational to PanLL’s architecture. Model.res holds all +state, Msg.res defines all messages, Update.res is the state transition +kernel. + +==== [CRITICAL] all-state-in-model + +*Rule:* ALL application state lives in Model.model — no global mutable +state, no module-level state, no window.* state + +*Why:* TEA requires single state tree. Anti-Crash and OrbitalSync depend +on this invariant for correctness. + +==== [CRITICAL] no-npm-bun + +*Rule:* No npm, Bun, pnpm, or yarn — Deno is the orchestrator + +*Why:* Deno-only build (post panll#65). ReScript and Tailwind run via +`+npm:+` specifiers in `+deno.json+` — there is no `+package.json+` and +no npm CLI is invoked. Do not reintroduce npm/bun/yarn/pnpm tooling. + +==== [CRITICAL] anticrash-validates-all + +*Rule:* Anti-Crash circuit breaker validates ALL neural tokens before +symbolic execution — never bypass this + +*Why:* Safety-critical: prevents untrusted neural output from corrupting +symbolic state. The validation path exists for a reason. + +==== [HIGH] panels-not-panes + +*Rule:* UI elements are called '`panels`', NEVER '`panes`', '`tabs`', or +'`windows`' + +*Why:* PanLL naming convention — '`panels`' is the correct term +everywhere in code, docs, and communication + +==== [CRITICAL] no-bulk-panel-deletion + +*Rule:* Do not delete more than 2 panel files in a single operation +without explicit user approval + +*Why:* 106 panels have complex interdependencies. Bulk deletion can +cascade and break OrbitalSync. + +==== [HIGH] gossamer-bridge-pattern + +*Rule:* Gossamer commands in src/commands/ are invoke wrappers only — do +not put business logic there + +*Why:* Business logic belongs in Update.res. Commands are thin bridges +to the Gossamer backend. + +==== [CRITICAL] binary-star-model + +*Rule:* The Binary Star architecture (Panel-L symbolic + Panel-N neural ++ Panel-W world) is deliberate — do not flatten into a single panel type + +*Why:* The three panel types serve fundamentally different roles. This +is the core design of PanLL. + +==== [CRITICAL] rescript-core-team + +*Rule:* The project owner is on the ReScript core team — do not suggest +migrating away from ReScript + +*Why:* ReScript is not a temporary choice. The owner contributes to +ReScript itself. + +=== Protected Files and Directories + +Do NOT delete, reorganise, or replace these without explicit user +approval: + +[width="100%",cols="43%,57%",options="header",] +|=== +|Path |Reason +|`+src/tea/+` |Custom TEA runtime — 18 modules. NEVER replace with +rescript-tea. + +|`+src/Model.res+` |Single state tree — all application state lives here + +|`+src/Msg.res+` |Message type definitions — the TEA message catalogue + +|`+src/Update.res+` |State transition kernel — ~7500 lines, the heart of +PanLL + +|`+src/View.res+` |Root view renderer + +|`+src/App.res+` |Application entry point + +|`+src/core/+` |Core engines — AntiCrash, OrbitalSync, Contractiles, +TypeLLEngine, VabEngine + +|`+src/components/+` |106 panel views — do not bulk-delete + +|`+src/commands/+` |Gossamer bridge commands — thin wrappers only + +|`+src/modules/+` |Module registry + TypeLLService — cross-panel type +intelligence + +|`+src-gossamer/+` |Rust backend (WebKitGTK) — Gossamer desktop +integration + +|`+beam/+` |Elixir/BEAM API layer + +|`+tests/+` |979 tests, 41 suites — never delete tests + +|`+.machine_readable/+` |Canonical location for A2ML state files — MUST +stay here + +|`+coordination.k9+` |This file — source of truth for AI coordination +|=== + +=== Architecture Decisions (Deliberate) + +These choices may look unusual but are intentional: + +==== gossamer-not-tauri + +*Decision:* Gossamer (Zig + WebKitGTK) is the desktop backend — +migration from Tauri 2.0 is complete + +*Why:* Gossamer is the hyperpolymath desktop runtime. Tauri was used +previously but replaced. + +*Rejected alternatives:* Tauri 2.0, Electron, native GTK + +==== custom-tea-not-rescript-tea + +*Decision:* Custom TEA runtime (src/tea/, 18 modules) instead of the +rescript-tea library + +*Why:* PanLL needs Anti-Crash integration, OrbitalSync, Vexometer hooks, +and panel lifecycle — none available in rescript-tea + +*Rejected alternatives:* rescript-tea, Redux, MobX, React hooks pattern + +==== deno-only-with-npm-specifiers + +*Decision:* Deno orchestrates everything; ReScript and Tailwind run via +`+npm:+` specifiers in `+deno.json+` + +*Why:* Post panll#65: `+package.json+` + `+package-lock.json+` deleted; +ReScript compiles via +`+deno run -A --allow-scripts=npm:rescript npm:rescript@^12.0.0 build+`, +Tailwind via `+deno run -A npm:tailwindcss+`. No npm CLI invocation. Do +not extend npm’s role. + +==== binary-star + +*Decision:* Four panel types: Panel-A (ambient/substrate), Panel-L +(logic/symbolic), Panel-N (neural/machine), Panel-W (world/shared) + +*Why:* L + N orbit W in the Binary Star core (clear separation of human +reasoning, machine inference, and shared world state); Panel-A surrounds +as ambient substrate for persistent context and ergonomic support. + +==== vexometer-cognitive-load + +*Decision:* Vexometer monitors operator stress and adapts UI detail +density + +*Why:* HTI (Human-Tool Interaction) principle — the IDE adapts to the +human, not vice versa + +==== anticrash-circuit-breaker + +*Decision:* Anti-Crash validates all neural tokens before they enter the +symbolic pipeline + +*Why:* Safety boundary between neural and symbolic systems — prevents +hallucinated code from corrupting state + +=== Do NOT Create + +These files, patterns, or systems must NOT be introduced: + +* ****/*.ts** — TypeScript is banned — use ReScript +* *Dockerfile* — Use Containerfile (Podman, not Docker) +* ****/*.py** — Python is banned — use ReScript, Rust, or Elixir +* *A replacement TEA runtime or state management library* — src/tea/ is +the TEA runtime — it is custom, deliberate, and must not be replaced +* *REST API endpoints parallel to existing Groove protocol endpoints* — +Groove is the inter-service communication protocol — do not create REST +alternatives +* *A new panel type beyond Panel-L, Panel-N, Panel-W* — Binary Star +model has exactly three types — adding more would break OrbitalSync +* *Direct Tauri imports or tauri.conf.json* — Tauri migration to +Gossamer is complete — do not reintroduce + +=== Terminology + +Use the correct terms for this project: + +* Say *"`panels`"*, NOT "`panes`", "`tabs`", "`windows`" +** PanLL UI elements are always called panels — this is enforced +everywhere +* Say *"`Binary Star`"*, NOT "`dual-pane`", "`split-view`", +"`two-panel`" +** The architectural model is Binary Star (Panel-L + Panel-N orbiting +Panel-W) +* Say *"`Anti-Crash`"*, NOT "`validator`", "`sanitizer`", "`filter`" +** The neural token validation system is called Anti-Crash +* Say *"`Vexometer`"*, NOT "`stress meter`", "`load indicator`", +"`fatigue tracker`" +** The cognitive load monitoring system is called Vexometer +* Say *"`OrbitalSync`"*, NOT "`state sync`", "`panel sync`", "`sync +engine`" +** The multi-panel state coherence system is called OrbitalSync + +=== Port Assignments + +[cols=",",options="header",] +|=== +|Service |Port +|dev-server |8000 +|echidna |9000 +|verisim |8080 +|boj-server |7700 +|typell |7800 +|=== + +=== Ecosystem Context + +*Depends on:* - *gossamer* — Desktop backend runtime (Zig + WebKitGTK) - +*verisim* — Persistent storage layer - *typell* — Type intelligence +engine — cross-panel type checking - *boj-server* — MCP server — all +external tool integration + +*Consumed by:* - *idaptik* — Uses PanLL as level editor for game content + +*Related projects:* - *echidna* — Proof engine — formal verification +integration - *hypatia* — Neurosymbolic CI/CD scanning - *panic-attack* +— Security scanning tool - *gitbot-fleet* — Bot orchestration (rhodibot, +echidnabot, etc.) - *proven* — Formally verified alternatives library diff --git a/.junie/guidelines.md b/.junie/guidelines.md deleted file mode 100644 index 7fd2b1c1..00000000 --- a/.junie/guidelines.md +++ /dev/null @@ -1,230 +0,0 @@ - - - - -# PanLL — AI Coordination Rules - -> **Auto-generated from `coordination.k9`** — do not edit directly. -> Re-generate with: `deno run --allow-read --allow-write generate.js coordination.k9` -> Source of truth: `coordination.k9` in repository root. - -## Project - -Neurosymbolic IDE built on the Binary Star model — human (symbolic, Panel-L) and machine (neural, Panel-N) orbiting a shared world state (Panel-W). 106 panels, custom TEA runtime, Gossamer desktop backend. - -**Languages:** ReScript, Rust, Elixir, JavaScript -**License:** MPL-2.0 -**Build system:** just -**Runtime:** deno - -## Build Commands - -| Command | Description | -|---------|-------------| -| `just build` | Full build (ReScript + CSS + bundle) | -| `just res` | ReScript compile only | -| `just bundle` | esbuild bundle | -| `just css` | Build CSS | -| `just dev` | Start dev server on port 8000 | -| `just test` | Run test suite (979 tests, 41 suites) | -| `just coverage` | Run tests with coverage | -| `just lint` | Lint ReScript source | -| `just doctor` | Run project health checks | - -## INVARIANTS — Do Not Violate - -These rules are non-negotiable. Violating them will break the project -or contradict deliberate architectural decisions. - -### [CRITICAL] custom-tea-runtime - -**Rule:** The custom TEA runtime in src/tea/ (18 modules) must NEVER be replaced with rescript-tea or any other library - -**Why:** rescript-tea was deliberately evaluated and rejected. The custom TEA runtime handles PanLL-specific needs: Anti-Crash circuit breaking, Vexometer cognitive load adaptation, OrbitalSync multi-panel state coherence, and panel lifecycle management. It is not legacy — it is the architecture. - -### [CRITICAL] no-typescript - -**Rule:** Do not introduce TypeScript files — ReScript is the frontend language - -**Why:** ReScript provides better type safety with less overhead. This is a deliberate, ecosystem-wide decision. - -### [CRITICAL] no-tauri - -**Rule:** Do not introduce Tauri references or dependencies — Gossamer is the desktop backend - -**Why:** PanLL was migrated FROM Tauri 2.0 TO Gossamer. This migration is complete and intentional. - -### [CRITICAL] tea-pattern-only - -**Rule:** All state management uses TEA (Model -> Msg -> Update -> View) — no MVC, Redux, hooks, or other patterns - -**Why:** TEA is foundational to PanLL's architecture. Model.res holds all state, Msg.res defines all messages, Update.res is the state transition kernel. - -### [CRITICAL] all-state-in-model - -**Rule:** ALL application state lives in Model.model — no global mutable state, no module-level state, no window.* state - -**Why:** TEA requires single state tree. Anti-Crash and OrbitalSync depend on this invariant for correctness. - -### [CRITICAL] no-npm-bun - -**Rule:** No npm, Bun, pnpm, or yarn — Deno is the orchestrator - -**Why:** Deno-only build (post panll#65). ReScript and Tailwind run via `npm:` specifiers in `deno.json` — there is no `package.json` and no npm CLI is invoked. Do not reintroduce npm/bun/yarn/pnpm tooling. - -### [CRITICAL] anticrash-validates-all - -**Rule:** Anti-Crash circuit breaker validates ALL neural tokens before symbolic execution — never bypass this - -**Why:** Safety-critical: prevents untrusted neural output from corrupting symbolic state. The validation path exists for a reason. - -### [HIGH] panels-not-panes - -**Rule:** UI elements are called 'panels', NEVER 'panes', 'tabs', or 'windows' - -**Why:** PanLL naming convention — 'panels' is the correct term everywhere in code, docs, and communication - -### [CRITICAL] no-bulk-panel-deletion - -**Rule:** Do not delete more than 2 panel files in a single operation without explicit user approval - -**Why:** 106 panels have complex interdependencies. Bulk deletion can cascade and break OrbitalSync. - -### [HIGH] gossamer-bridge-pattern - -**Rule:** Gossamer commands in src/commands/ are invoke wrappers only — do not put business logic there - -**Why:** Business logic belongs in Update.res. Commands are thin bridges to the Gossamer backend. - -### [CRITICAL] binary-star-model - -**Rule:** The Binary Star architecture (Panel-L symbolic + Panel-N neural + Panel-W world) is deliberate — do not flatten into a single panel type - -**Why:** The three panel types serve fundamentally different roles. This is the core design of PanLL. - -### [CRITICAL] rescript-core-team - -**Rule:** The project owner is on the ReScript core team — do not suggest migrating away from ReScript - -**Why:** ReScript is not a temporary choice. The owner contributes to ReScript itself. - -## Protected Files and Directories - -Do NOT delete, reorganise, or replace these without explicit user approval: - -| Path | Reason | -|------|--------| -| `src/tea/` | Custom TEA runtime — 18 modules. NEVER replace with rescript-tea. | -| `src/Model.res` | Single state tree — all application state lives here | -| `src/Msg.res` | Message type definitions — the TEA message catalogue | -| `src/Update.res` | State transition kernel — ~7500 lines, the heart of PanLL | -| `src/View.res` | Root view renderer | -| `src/App.res` | Application entry point | -| `src/core/` | Core engines — AntiCrash, OrbitalSync, Contractiles, TypeLLEngine, VabEngine | -| `src/components/` | 106 panel views — do not bulk-delete | -| `src/commands/` | Gossamer bridge commands — thin wrappers only | -| `src/modules/` | Module registry + TypeLLService — cross-panel type intelligence | -| `src-gossamer/` | Rust backend (WebKitGTK) — Gossamer desktop integration | -| `beam/` | Elixir/BEAM API layer | -| `tests/` | 979 tests, 41 suites — never delete tests | -| `.machine_readable/` | Canonical location for A2ML state files — MUST stay here | -| `coordination.k9` | This file — source of truth for AI coordination | - -## Architecture Decisions (Deliberate) - -These choices may look unusual but are intentional: - -### gossamer-not-tauri - -**Decision:** Gossamer (Zig + WebKitGTK) is the desktop backend — migration from Tauri 2.0 is complete - -**Why:** Gossamer is the hyperpolymath desktop runtime. Tauri was used previously but replaced. - -**Rejected alternatives:** Tauri 2.0, Electron, native GTK - -### custom-tea-not-rescript-tea - -**Decision:** Custom TEA runtime (src/tea/, 18 modules) instead of the rescript-tea library - -**Why:** PanLL needs Anti-Crash integration, OrbitalSync, Vexometer hooks, and panel lifecycle — none available in rescript-tea - -**Rejected alternatives:** rescript-tea, Redux, MobX, React hooks pattern - -### deno-only-with-npm-specifiers - -**Decision:** Deno orchestrates everything; ReScript and Tailwind run via `npm:` specifiers in `deno.json` - -**Why:** Post panll#65: `package.json` + `package-lock.json` deleted; ReScript compiles via `deno run -A --allow-scripts=npm:rescript npm:rescript@^12.0.0 build`, Tailwind via `deno run -A npm:tailwindcss`. No npm CLI invocation. Do not extend npm's role. - -### binary-star - -**Decision:** Four panel types: Panel-A (ambient/substrate), Panel-L (logic/symbolic), Panel-N (neural/machine), Panel-W (world/shared) - -**Why:** L + N orbit W in the Binary Star core (clear separation of human reasoning, machine inference, and shared world state); Panel-A surrounds as ambient substrate for persistent context and ergonomic support. - -### vexometer-cognitive-load - -**Decision:** Vexometer monitors operator stress and adapts UI detail density - -**Why:** HTI (Human-Tool Interaction) principle — the IDE adapts to the human, not vice versa - -### anticrash-circuit-breaker - -**Decision:** Anti-Crash validates all neural tokens before they enter the symbolic pipeline - -**Why:** Safety boundary between neural and symbolic systems — prevents hallucinated code from corrupting state - -## Do NOT Create - -These files, patterns, or systems must NOT be introduced: - -- ****/*.ts** — TypeScript is banned — use ReScript -- **Dockerfile** — Use Containerfile (Podman, not Docker) -- ****/*.py** — Python is banned — use ReScript, Rust, or Elixir -- **A replacement TEA runtime or state management library** — src/tea/ is the TEA runtime — it is custom, deliberate, and must not be replaced -- **REST API endpoints parallel to existing Groove protocol endpoints** — Groove is the inter-service communication protocol — do not create REST alternatives -- **A new panel type beyond Panel-L, Panel-N, Panel-W** — Binary Star model has exactly three types — adding more would break OrbitalSync -- **Direct Tauri imports or tauri.conf.json** — Tauri migration to Gossamer is complete — do not reintroduce - -## Terminology - -Use the correct terms for this project: - -- Say **"panels"**, NOT "panes", "tabs", "windows" - - PanLL UI elements are always called panels — this is enforced everywhere -- Say **"Binary Star"**, NOT "dual-pane", "split-view", "two-panel" - - The architectural model is Binary Star (Panel-L + Panel-N orbiting Panel-W) -- Say **"Anti-Crash"**, NOT "validator", "sanitizer", "filter" - - The neural token validation system is called Anti-Crash -- Say **"Vexometer"**, NOT "stress meter", "load indicator", "fatigue tracker" - - The cognitive load monitoring system is called Vexometer -- Say **"OrbitalSync"**, NOT "state sync", "panel sync", "sync engine" - - The multi-panel state coherence system is called OrbitalSync - -## Port Assignments - -| Service | Port | -|---------|------| -| dev-server | 8000 | -| echidna | 9000 | -| verisim | 8080 | -| boj-server | 7700 | -| typell | 7800 | - -## Ecosystem Context - -**Depends on:** -- **gossamer** — Desktop backend runtime (Zig + WebKitGTK) -- **verisim** — Persistent storage layer -- **typell** — Type intelligence engine — cross-panel type checking -- **boj-server** — MCP server — all external tool integration - -**Consumed by:** -- **idaptik** — Uses PanLL as level editor for game content - -**Related projects:** -- **echidna** — Proof engine — formal verification integration -- **hypatia** — Neurosymbolic CI/CD scanning -- **panic-attack** — Security scanning tool -- **gitbot-fleet** — Bot orchestration (rhodibot, echidnabot, etc.) -- **proven** — Formally verified alternatives library diff --git a/.q/rules/coordination.adoc b/.q/rules/coordination.adoc new file mode 100644 index 00000000..ece4f046 --- /dev/null +++ b/.q/rules/coordination.adoc @@ -0,0 +1,302 @@ +== PanLL — AI Coordination Rules + +____ +*Auto-generated from `+coordination.k9+`* — do not edit directly. +Re-generate with: +`+deno run --allow-read --allow-write generate.js coordination.k9+` +Source of truth: `+coordination.k9+` in repository root. +____ + +=== Project + +Neurosymbolic IDE built on the Binary Star model — human (symbolic, +Panel-L) and machine (neural, Panel-N) orbiting a shared world state +(Panel-W). 106 panels, custom TEA runtime, Gossamer desktop backend. + +*Languages:* ReScript, Rust, Elixir, JavaScript *License:* MPL-2.0 +*Build system:* just *Runtime:* deno + +=== Build Commands + +[cols=",",options="header",] +|=== +|Command |Description +|`+just build+` |Full build (ReScript + CSS + bundle) +|`+just res+` |ReScript compile only +|`+just bundle+` |esbuild bundle +|`+just css+` |Build CSS +|`+just dev+` |Start dev server on port 8000 +|`+just test+` |Run test suite (979 tests, 41 suites) +|`+just coverage+` |Run tests with coverage +|`+just lint+` |Lint ReScript source +|`+just doctor+` |Run project health checks +|=== + +=== INVARIANTS — Do Not Violate + +These rules are non-negotiable. Violating them will break the project or +contradict deliberate architectural decisions. + +==== [CRITICAL] custom-tea-runtime + +*Rule:* The custom TEA runtime in src/tea/ (18 modules) must NEVER be +replaced with rescript-tea or any other library + +*Why:* rescript-tea was deliberately evaluated and rejected. The custom +TEA runtime handles PanLL-specific needs: Anti-Crash circuit breaking, +Vexometer cognitive load adaptation, OrbitalSync multi-panel state +coherence, and panel lifecycle management. It is not legacy — it is the +architecture. + +==== [CRITICAL] no-typescript + +*Rule:* Do not introduce TypeScript files — ReScript is the frontend +language + +*Why:* ReScript provides better type safety with less overhead. This is +a deliberate, ecosystem-wide decision. + +==== [CRITICAL] no-tauri + +*Rule:* Do not introduce Tauri references or dependencies — Gossamer is +the desktop backend + +*Why:* PanLL was migrated FROM Tauri 2.0 TO Gossamer. This migration is +complete and intentional. + +==== [CRITICAL] tea-pattern-only + +*Rule:* All state management uses TEA (Model -> Msg -> Update -> View) — +no MVC, Redux, hooks, or other patterns + +*Why:* TEA is foundational to PanLL’s architecture. Model.res holds all +state, Msg.res defines all messages, Update.res is the state transition +kernel. + +==== [CRITICAL] all-state-in-model + +*Rule:* ALL application state lives in Model.model — no global mutable +state, no module-level state, no window.* state + +*Why:* TEA requires single state tree. Anti-Crash and OrbitalSync depend +on this invariant for correctness. + +==== [CRITICAL] no-npm-bun + +*Rule:* No npm, Bun, pnpm, or yarn — Deno is the orchestrator + +*Why:* npm is used ONLY for the ReScript compiler (which requires it). +All other tooling uses Deno. Do not add npm dependencies. + +==== [CRITICAL] anticrash-validates-all + +*Rule:* Anti-Crash circuit breaker validates ALL neural tokens before +symbolic execution — never bypass this + +*Why:* Safety-critical: prevents untrusted neural output from corrupting +symbolic state. The validation path exists for a reason. + +==== [HIGH] panels-not-panes + +*Rule:* UI elements are called '`panels`', NEVER '`panes`', '`tabs`', or +'`windows`' + +*Why:* PanLL naming convention — '`panels`' is the correct term +everywhere in code, docs, and communication + +==== [CRITICAL] no-bulk-panel-deletion + +*Rule:* Do not delete more than 2 panel files in a single operation +without explicit user approval + +*Why:* 106 panels have complex interdependencies. Bulk deletion can +cascade and break OrbitalSync. + +==== [HIGH] gossamer-bridge-pattern + +*Rule:* Gossamer commands in src/commands/ are invoke wrappers only — do +not put business logic there + +*Why:* Business logic belongs in Update.res. Commands are thin bridges +to the Gossamer backend. + +==== [CRITICAL] binary-star-model + +*Rule:* The Binary Star architecture (Panel-L symbolic + Panel-N neural ++ Panel-W world) is deliberate — do not flatten into a single panel type + +*Why:* The three panel types serve fundamentally different roles. This +is the core design of PanLL. + +==== [CRITICAL] rescript-core-team + +*Rule:* The project owner is on the ReScript core team — do not suggest +migrating away from ReScript + +*Why:* ReScript is not a temporary choice. The owner contributes to +ReScript itself. + +=== Protected Files and Directories + +Do NOT delete, reorganise, or replace these without explicit user +approval: + +[width="100%",cols="43%,57%",options="header",] +|=== +|Path |Reason +|`+src/tea/+` |Custom TEA runtime — 18 modules. NEVER replace with +rescript-tea. + +|`+src/Model.res+` |Single state tree — all application state lives here + +|`+src/Msg.res+` |Message type definitions — the TEA message catalogue + +|`+src/Update.res+` |State transition kernel — ~7500 lines, the heart of +PanLL + +|`+src/View.res+` |Root view renderer + +|`+src/App.res+` |Application entry point + +|`+src/core/+` |Core engines — AntiCrash, OrbitalSync, Contractiles, +TypeLLEngine, VabEngine + +|`+src/components/+` |106 panel views — do not bulk-delete + +|`+src/commands/+` |Gossamer bridge commands — thin wrappers only + +|`+src/modules/+` |Module registry + TypeLLService — cross-panel type +intelligence + +|`+src-gossamer/+` |Rust backend (WebKitGTK) — Gossamer desktop +integration + +|`+beam/+` |Elixir/BEAM API layer + +|`+tests/+` |979 tests, 41 suites — never delete tests + +|`+.machine_readable/+` |Canonical location for A2ML state files — MUST +stay here + +|`+coordination.k9+` |This file — source of truth for AI coordination +|=== + +=== Architecture Decisions (Deliberate) + +These choices may look unusual but are intentional: + +==== gossamer-not-tauri + +*Decision:* Gossamer (Zig + WebKitGTK) is the desktop backend — +migration from Tauri 2.0 is complete + +*Why:* Gossamer is the hyperpolymath desktop runtime. Tauri was used +previously but replaced. + +*Rejected alternatives:* Tauri 2.0, Electron, native GTK + +==== custom-tea-not-rescript-tea + +*Decision:* Custom TEA runtime (src/tea/, 18 modules) instead of the +rescript-tea library + +*Why:* PanLL needs Anti-Crash integration, OrbitalSync, Vexometer hooks, +and panel lifecycle — none available in rescript-tea + +*Rejected alternatives:* rescript-tea, Redux, MobX, React hooks pattern + +==== deno-npm-hybrid + +*Decision:* Deno orchestrates everything, but npm is used solely for the +ReScript compiler + +*Why:* ReScript compiler requires npm — this is the ONLY permitted npm +usage. Do not extend npm’s role. + +==== binary-star + +*Decision:* Four panel types: Panel-A (ambient/substrate), Panel-L +(logic/symbolic), Panel-N (neural/machine), Panel-W (world/shared) + +*Why:* L + N orbit W in the Binary Star core (clear separation of human +reasoning, machine inference, and shared world state); Panel-A surrounds +as ambient substrate for persistent context and ergonomic support. + +==== vexometer-cognitive-load + +*Decision:* Vexometer monitors operator stress and adapts UI detail +density + +*Why:* HTI (Human-Tool Interaction) principle — the IDE adapts to the +human, not vice versa + +==== anticrash-circuit-breaker + +*Decision:* Anti-Crash validates all neural tokens before they enter the +symbolic pipeline + +*Why:* Safety boundary between neural and symbolic systems — prevents +hallucinated code from corrupting state + +=== Do NOT Create + +These files, patterns, or systems must NOT be introduced: + +* ****/*.ts** — TypeScript is banned — use ReScript +* *Dockerfile* — Use Containerfile (Podman, not Docker) +* ****/*.py** — Python is banned — use ReScript, Rust, or Elixir +* *A replacement TEA runtime or state management library* — src/tea/ is +the TEA runtime — it is custom, deliberate, and must not be replaced +* *REST API endpoints parallel to existing Groove protocol endpoints* — +Groove is the inter-service communication protocol — do not create REST +alternatives +* *A new panel type beyond Panel-L, Panel-N, Panel-W* — Binary Star +model has exactly three types — adding more would break OrbitalSync +* *Direct Tauri imports or tauri.conf.json* — Tauri migration to +Gossamer is complete — do not reintroduce + +=== Terminology + +Use the correct terms for this project: + +* Say *"`panels`"*, NOT "`panes`", "`tabs`", "`windows`" +** PanLL UI elements are always called panels — this is enforced +everywhere +* Say *"`Binary Star`"*, NOT "`dual-pane`", "`split-view`", +"`two-panel`" +** The architectural model is Binary Star (Panel-L + Panel-N orbiting +Panel-W) +* Say *"`Anti-Crash`"*, NOT "`validator`", "`sanitizer`", "`filter`" +** The neural token validation system is called Anti-Crash +* Say *"`Vexometer`"*, NOT "`stress meter`", "`load indicator`", +"`fatigue tracker`" +** The cognitive load monitoring system is called Vexometer +* Say *"`OrbitalSync`"*, NOT "`state sync`", "`panel sync`", "`sync +engine`" +** The multi-panel state coherence system is called OrbitalSync + +=== Port Assignments + +[cols=",",options="header",] +|=== +|Service |Port +|dev-server |8000 +|echidna |9000 +|verisim |8080 +|boj-server |7700 +|typell |7800 +|=== + +=== Ecosystem Context + +*Depends on:* - *gossamer* — Desktop backend runtime (Zig + WebKitGTK) - +*verisim* — Persistent storage layer - *typell* — Type intelligence +engine — cross-panel type checking - *boj-server* — MCP server — all +external tool integration + +*Consumed by:* - *idaptik* — Uses PanLL as level editor for game content + +*Related projects:* - *echidna* — Proof engine — formal verification +integration - *hypatia* — Neurosymbolic CI/CD scanning - *panic-attack* +— Security scanning tool - *gitbot-fleet* — Bot orchestration (rhodibot, +echidnabot, etc.) - *proven* — Formally verified alternatives library diff --git a/.q/rules/coordination.md b/.q/rules/coordination.md deleted file mode 100644 index 4053034c..00000000 --- a/.q/rules/coordination.md +++ /dev/null @@ -1,230 +0,0 @@ - - - - -# PanLL — AI Coordination Rules - -> **Auto-generated from `coordination.k9`** — do not edit directly. -> Re-generate with: `deno run --allow-read --allow-write generate.js coordination.k9` -> Source of truth: `coordination.k9` in repository root. - -## Project - -Neurosymbolic IDE built on the Binary Star model — human (symbolic, Panel-L) and machine (neural, Panel-N) orbiting a shared world state (Panel-W). 106 panels, custom TEA runtime, Gossamer desktop backend. - -**Languages:** ReScript, Rust, Elixir, JavaScript -**License:** MPL-2.0 -**Build system:** just -**Runtime:** deno - -## Build Commands - -| Command | Description | -|---------|-------------| -| `just build` | Full build (ReScript + CSS + bundle) | -| `just res` | ReScript compile only | -| `just bundle` | esbuild bundle | -| `just css` | Build CSS | -| `just dev` | Start dev server on port 8000 | -| `just test` | Run test suite (979 tests, 41 suites) | -| `just coverage` | Run tests with coverage | -| `just lint` | Lint ReScript source | -| `just doctor` | Run project health checks | - -## INVARIANTS — Do Not Violate - -These rules are non-negotiable. Violating them will break the project -or contradict deliberate architectural decisions. - -### [CRITICAL] custom-tea-runtime - -**Rule:** The custom TEA runtime in src/tea/ (18 modules) must NEVER be replaced with rescript-tea or any other library - -**Why:** rescript-tea was deliberately evaluated and rejected. The custom TEA runtime handles PanLL-specific needs: Anti-Crash circuit breaking, Vexometer cognitive load adaptation, OrbitalSync multi-panel state coherence, and panel lifecycle management. It is not legacy — it is the architecture. - -### [CRITICAL] no-typescript - -**Rule:** Do not introduce TypeScript files — ReScript is the frontend language - -**Why:** ReScript provides better type safety with less overhead. This is a deliberate, ecosystem-wide decision. - -### [CRITICAL] no-tauri - -**Rule:** Do not introduce Tauri references or dependencies — Gossamer is the desktop backend - -**Why:** PanLL was migrated FROM Tauri 2.0 TO Gossamer. This migration is complete and intentional. - -### [CRITICAL] tea-pattern-only - -**Rule:** All state management uses TEA (Model -> Msg -> Update -> View) — no MVC, Redux, hooks, or other patterns - -**Why:** TEA is foundational to PanLL's architecture. Model.res holds all state, Msg.res defines all messages, Update.res is the state transition kernel. - -### [CRITICAL] all-state-in-model - -**Rule:** ALL application state lives in Model.model — no global mutable state, no module-level state, no window.* state - -**Why:** TEA requires single state tree. Anti-Crash and OrbitalSync depend on this invariant for correctness. - -### [CRITICAL] no-npm-bun - -**Rule:** No npm, Bun, pnpm, or yarn — Deno is the orchestrator - -**Why:** npm is used ONLY for the ReScript compiler (which requires it). All other tooling uses Deno. Do not add npm dependencies. - -### [CRITICAL] anticrash-validates-all - -**Rule:** Anti-Crash circuit breaker validates ALL neural tokens before symbolic execution — never bypass this - -**Why:** Safety-critical: prevents untrusted neural output from corrupting symbolic state. The validation path exists for a reason. - -### [HIGH] panels-not-panes - -**Rule:** UI elements are called 'panels', NEVER 'panes', 'tabs', or 'windows' - -**Why:** PanLL naming convention — 'panels' is the correct term everywhere in code, docs, and communication - -### [CRITICAL] no-bulk-panel-deletion - -**Rule:** Do not delete more than 2 panel files in a single operation without explicit user approval - -**Why:** 106 panels have complex interdependencies. Bulk deletion can cascade and break OrbitalSync. - -### [HIGH] gossamer-bridge-pattern - -**Rule:** Gossamer commands in src/commands/ are invoke wrappers only — do not put business logic there - -**Why:** Business logic belongs in Update.res. Commands are thin bridges to the Gossamer backend. - -### [CRITICAL] binary-star-model - -**Rule:** The Binary Star architecture (Panel-L symbolic + Panel-N neural + Panel-W world) is deliberate — do not flatten into a single panel type - -**Why:** The three panel types serve fundamentally different roles. This is the core design of PanLL. - -### [CRITICAL] rescript-core-team - -**Rule:** The project owner is on the ReScript core team — do not suggest migrating away from ReScript - -**Why:** ReScript is not a temporary choice. The owner contributes to ReScript itself. - -## Protected Files and Directories - -Do NOT delete, reorganise, or replace these without explicit user approval: - -| Path | Reason | -|------|--------| -| `src/tea/` | Custom TEA runtime — 18 modules. NEVER replace with rescript-tea. | -| `src/Model.res` | Single state tree — all application state lives here | -| `src/Msg.res` | Message type definitions — the TEA message catalogue | -| `src/Update.res` | State transition kernel — ~7500 lines, the heart of PanLL | -| `src/View.res` | Root view renderer | -| `src/App.res` | Application entry point | -| `src/core/` | Core engines — AntiCrash, OrbitalSync, Contractiles, TypeLLEngine, VabEngine | -| `src/components/` | 106 panel views — do not bulk-delete | -| `src/commands/` | Gossamer bridge commands — thin wrappers only | -| `src/modules/` | Module registry + TypeLLService — cross-panel type intelligence | -| `src-gossamer/` | Rust backend (WebKitGTK) — Gossamer desktop integration | -| `beam/` | Elixir/BEAM API layer | -| `tests/` | 979 tests, 41 suites — never delete tests | -| `.machine_readable/` | Canonical location for A2ML state files — MUST stay here | -| `coordination.k9` | This file — source of truth for AI coordination | - -## Architecture Decisions (Deliberate) - -These choices may look unusual but are intentional: - -### gossamer-not-tauri - -**Decision:** Gossamer (Zig + WebKitGTK) is the desktop backend — migration from Tauri 2.0 is complete - -**Why:** Gossamer is the hyperpolymath desktop runtime. Tauri was used previously but replaced. - -**Rejected alternatives:** Tauri 2.0, Electron, native GTK - -### custom-tea-not-rescript-tea - -**Decision:** Custom TEA runtime (src/tea/, 18 modules) instead of the rescript-tea library - -**Why:** PanLL needs Anti-Crash integration, OrbitalSync, Vexometer hooks, and panel lifecycle — none available in rescript-tea - -**Rejected alternatives:** rescript-tea, Redux, MobX, React hooks pattern - -### deno-npm-hybrid - -**Decision:** Deno orchestrates everything, but npm is used solely for the ReScript compiler - -**Why:** ReScript compiler requires npm — this is the ONLY permitted npm usage. Do not extend npm's role. - -### binary-star - -**Decision:** Four panel types: Panel-A (ambient/substrate), Panel-L (logic/symbolic), Panel-N (neural/machine), Panel-W (world/shared) - -**Why:** L + N orbit W in the Binary Star core (clear separation of human reasoning, machine inference, and shared world state); Panel-A surrounds as ambient substrate for persistent context and ergonomic support. - -### vexometer-cognitive-load - -**Decision:** Vexometer monitors operator stress and adapts UI detail density - -**Why:** HTI (Human-Tool Interaction) principle — the IDE adapts to the human, not vice versa - -### anticrash-circuit-breaker - -**Decision:** Anti-Crash validates all neural tokens before they enter the symbolic pipeline - -**Why:** Safety boundary between neural and symbolic systems — prevents hallucinated code from corrupting state - -## Do NOT Create - -These files, patterns, or systems must NOT be introduced: - -- ****/*.ts** — TypeScript is banned — use ReScript -- **Dockerfile** — Use Containerfile (Podman, not Docker) -- ****/*.py** — Python is banned — use ReScript, Rust, or Elixir -- **A replacement TEA runtime or state management library** — src/tea/ is the TEA runtime — it is custom, deliberate, and must not be replaced -- **REST API endpoints parallel to existing Groove protocol endpoints** — Groove is the inter-service communication protocol — do not create REST alternatives -- **A new panel type beyond Panel-L, Panel-N, Panel-W** — Binary Star model has exactly three types — adding more would break OrbitalSync -- **Direct Tauri imports or tauri.conf.json** — Tauri migration to Gossamer is complete — do not reintroduce - -## Terminology - -Use the correct terms for this project: - -- Say **"panels"**, NOT "panes", "tabs", "windows" - - PanLL UI elements are always called panels — this is enforced everywhere -- Say **"Binary Star"**, NOT "dual-pane", "split-view", "two-panel" - - The architectural model is Binary Star (Panel-L + Panel-N orbiting Panel-W) -- Say **"Anti-Crash"**, NOT "validator", "sanitizer", "filter" - - The neural token validation system is called Anti-Crash -- Say **"Vexometer"**, NOT "stress meter", "load indicator", "fatigue tracker" - - The cognitive load monitoring system is called Vexometer -- Say **"OrbitalSync"**, NOT "state sync", "panel sync", "sync engine" - - The multi-panel state coherence system is called OrbitalSync - -## Port Assignments - -| Service | Port | -|---------|------| -| dev-server | 8000 | -| echidna | 9000 | -| verisim | 8080 | -| boj-server | 7700 | -| typell | 7800 | - -## Ecosystem Context - -**Depends on:** -- **gossamer** — Desktop backend runtime (Zig + WebKitGTK) -- **verisim** — Persistent storage layer -- **typell** — Type intelligence engine — cross-panel type checking -- **boj-server** — MCP server — all external tool integration - -**Consumed by:** -- **idaptik** — Uses PanLL as level editor for game content - -**Related projects:** -- **echidna** — Proof engine — formal verification integration -- **hypatia** — Neurosymbolic CI/CD scanning -- **panic-attack** — Security scanning tool -- **gitbot-fleet** — Bot orchestration (rhodibot, echidnabot, etc.) -- **proven** — Formally verified alternatives library diff --git a/AGENTS.adoc b/AGENTS.adoc new file mode 100644 index 00000000..b4125b96 --- /dev/null +++ b/AGENTS.adoc @@ -0,0 +1,305 @@ +== PanLL — AI Coordination Rules + +____ +*Auto-generated from `+coordination.k9+`* — do not edit directly. +Re-generate with: +`+deno run --allow-read --allow-write generate.js coordination.k9+` +Source of truth: `+coordination.k9+` in repository root. +____ + +=== Project + +Neurosymbolic IDE built on the Binary Star model — human (symbolic, +Panel-L) and machine (neural, Panel-N) orbiting a shared world state +(Panel-W). 106 panels, custom TEA runtime, Gossamer desktop backend. + +*Languages:* ReScript, Rust, Elixir, JavaScript *License:* MPL-2.0 +*Build system:* just *Runtime:* deno + +=== Build Commands + +[cols=",",options="header",] +|=== +|Command |Description +|`+just build+` |Full build (ReScript + CSS + bundle) +|`+just res+` |ReScript compile only +|`+just bundle+` |esbuild bundle +|`+just css+` |Build CSS +|`+just dev+` |Start dev server on port 8000 +|`+just test+` |Run test suite (979 tests, 41 suites) +|`+just coverage+` |Run tests with coverage +|`+just lint+` |Lint ReScript source +|`+just doctor+` |Run project health checks +|=== + +=== INVARIANTS — Do Not Violate + +These rules are non-negotiable. Violating them will break the project or +contradict deliberate architectural decisions. + +==== [CRITICAL] custom-tea-runtime + +*Rule:* The custom TEA runtime in src/tea/ (18 modules) must NEVER be +replaced with rescript-tea or any other library + +*Why:* rescript-tea was deliberately evaluated and rejected. The custom +TEA runtime handles PanLL-specific needs: Anti-Crash circuit breaking, +Vexometer cognitive load adaptation, OrbitalSync multi-panel state +coherence, and panel lifecycle management. It is not legacy — it is the +architecture. + +==== [CRITICAL] no-typescript + +*Rule:* Do not introduce TypeScript files — ReScript is the frontend +language + +*Why:* ReScript provides better type safety with less overhead. This is +a deliberate, ecosystem-wide decision. + +==== [CRITICAL] no-tauri + +*Rule:* Do not introduce Tauri references or dependencies — Gossamer is +the desktop backend + +*Why:* PanLL was migrated FROM Tauri 2.0 TO Gossamer. This migration is +complete and intentional. + +==== [CRITICAL] tea-pattern-only + +*Rule:* All state management uses TEA (Model -> Msg -> Update -> View) — +no MVC, Redux, hooks, or other patterns + +*Why:* TEA is foundational to PanLL’s architecture. Model.res holds all +state, Msg.res defines all messages, Update.res is the state transition +kernel. + +==== [CRITICAL] all-state-in-model + +*Rule:* ALL application state lives in Model.model — no global mutable +state, no module-level state, no window.* state + +*Why:* TEA requires single state tree. Anti-Crash and OrbitalSync depend +on this invariant for correctness. + +==== [CRITICAL] no-npm-bun + +*Rule:* No npm, Bun, pnpm, or yarn — Deno is the orchestrator + +*Why:* Deno-only build (post panll#65). ReScript and Tailwind run via +`+npm:+` specifiers in `+deno.json+` — there is no `+package.json+` and +no npm CLI is invoked. Do not reintroduce npm/bun/yarn/pnpm tooling. + +==== [CRITICAL] anticrash-validates-all + +*Rule:* Anti-Crash circuit breaker validates ALL neural tokens before +symbolic execution — never bypass this + +*Why:* Safety-critical: prevents untrusted neural output from corrupting +symbolic state. The validation path exists for a reason. + +==== [HIGH] panels-not-panes + +*Rule:* UI elements are called '`panels`', NEVER '`panes`', '`tabs`', or +'`windows`' + +*Why:* PanLL naming convention — '`panels`' is the correct term +everywhere in code, docs, and communication + +==== [CRITICAL] no-bulk-panel-deletion + +*Rule:* Do not delete more than 2 panel files in a single operation +without explicit user approval + +*Why:* 106 panels have complex interdependencies. Bulk deletion can +cascade and break OrbitalSync. + +==== [HIGH] gossamer-bridge-pattern + +*Rule:* Gossamer commands in src/commands/ are invoke wrappers only — do +not put business logic there + +*Why:* Business logic belongs in Update.res. Commands are thin bridges +to the Gossamer backend. + +==== [CRITICAL] binary-star-model + +*Rule:* The Binary Star architecture (Panel-L symbolic + Panel-N neural ++ Panel-W world) is deliberate — do not flatten into a single panel type + +*Why:* The three panel types serve fundamentally different roles. This +is the core design of PanLL. + +==== [CRITICAL] rescript-core-team + +*Rule:* The project owner is on the ReScript core team — do not suggest +migrating away from ReScript + +*Why:* ReScript is not a temporary choice. The owner contributes to +ReScript itself. + +=== Protected Files and Directories + +Do NOT delete, reorganise, or replace these without explicit user +approval: + +[width="100%",cols="43%,57%",options="header",] +|=== +|Path |Reason +|`+src/tea/+` |Custom TEA runtime — 18 modules. NEVER replace with +rescript-tea. + +|`+src/Model.res+` |Single state tree — all application state lives here + +|`+src/Msg.res+` |Message type definitions — the TEA message catalogue + +|`+src/Update.res+` |State transition kernel — ~7500 lines, the heart of +PanLL + +|`+src/View.res+` |Root view renderer + +|`+src/App.res+` |Application entry point + +|`+src/core/+` |Core engines — AntiCrash, OrbitalSync, Contractiles, +TypeLLEngine, VabEngine + +|`+src/components/+` |106 panel views — do not bulk-delete + +|`+src/commands/+` |Gossamer bridge commands — thin wrappers only + +|`+src/modules/+` |Module registry + TypeLLService — cross-panel type +intelligence + +|`+src-gossamer/+` |Rust backend (WebKitGTK) — Gossamer desktop +integration + +|`+beam/+` |Elixir/BEAM API layer + +|`+tests/+` |979 tests, 41 suites — never delete tests + +|`+.machine_readable/+` |Canonical location for A2ML state files — MUST +stay here + +|`+coordination.k9+` |This file — source of truth for AI coordination +|=== + +=== Architecture Decisions (Deliberate) + +These choices may look unusual but are intentional: + +==== gossamer-not-tauri + +*Decision:* Gossamer (Zig + WebKitGTK) is the desktop backend — +migration from Tauri 2.0 is complete + +*Why:* Gossamer is the hyperpolymath desktop runtime. Tauri was used +previously but replaced. + +*Rejected alternatives:* Tauri 2.0, Electron, native GTK + +==== custom-tea-not-rescript-tea + +*Decision:* Custom TEA runtime (src/tea/, 18 modules) instead of the +rescript-tea library + +*Why:* PanLL needs Anti-Crash integration, OrbitalSync, Vexometer hooks, +and panel lifecycle — none available in rescript-tea + +*Rejected alternatives:* rescript-tea, Redux, MobX, React hooks pattern + +==== deno-only-with-npm-specifiers + +*Decision:* Deno orchestrates everything; ReScript and Tailwind run via +`+npm:+` specifiers in `+deno.json+` + +*Why:* Post panll#65: `+package.json+` + `+package-lock.json+` deleted; +ReScript compiles via +`+deno run -A --allow-scripts=npm:rescript npm:rescript@^12.0.0 build+`, +Tailwind via `+deno run -A npm:tailwindcss+`. No npm CLI invocation. Do +not extend npm’s role. + +==== binary-star + +*Decision:* Three panel types: Panel-L (symbolic/human), Panel-N +(neural/machine), Panel-W (world/shared) + +*Why:* Neurosymbolic architecture requires clear separation of human +reasoning, machine inference, and shared world state + +==== vexometer-cognitive-load + +*Decision:* Vexometer monitors operator stress and adapts UI detail +density + +*Why:* HTI (Human-Tool Interaction) principle — the IDE adapts to the +human, not vice versa + +==== anticrash-circuit-breaker + +*Decision:* Anti-Crash validates all neural tokens before they enter the +symbolic pipeline + +*Why:* Safety boundary between neural and symbolic systems — prevents +hallucinated code from corrupting state + +=== Do NOT Create + +These files, patterns, or systems must NOT be introduced: + +* ****/*.ts** — TypeScript is banned — use ReScript +* *Dockerfile* — Use Containerfile (Podman, not Docker) +* ****/*.py** — Python is banned — use ReScript, Rust, or Elixir +* *A replacement TEA runtime or state management library* — src/tea/ is +the TEA runtime — it is custom, deliberate, and must not be replaced +* *REST API endpoints parallel to existing Groove protocol endpoints* — +Groove is the inter-service communication protocol — do not create REST +alternatives +* *A new panel type beyond Panel-L, Panel-N, Panel-W* — Binary Star +model has exactly three types — adding more would break OrbitalSync +* *Direct Tauri imports or tauri.conf.json* — Tauri migration to +Gossamer is complete — do not reintroduce + +=== Terminology + +Use the correct terms for this project: + +* Say *"`panels`"*, NOT "`panes`", "`tabs`", "`windows`" +** PanLL UI elements are always called panels — this is enforced +everywhere +* Say *"`Binary Star`"*, NOT "`dual-pane`", "`split-view`", +"`two-panel`" +** The architectural model is Binary Star (Panel-L + Panel-N orbiting +Panel-W) +* Say *"`Anti-Crash`"*, NOT "`validator`", "`sanitizer`", "`filter`" +** The neural token validation system is called Anti-Crash +* Say *"`Vexometer`"*, NOT "`stress meter`", "`load indicator`", +"`fatigue tracker`" +** The cognitive load monitoring system is called Vexometer +* Say *"`OrbitalSync`"*, NOT "`state sync`", "`panel sync`", "`sync +engine`" +** The multi-panel state coherence system is called OrbitalSync + +=== Port Assignments + +[cols=",",options="header",] +|=== +|Service |Port +|dev-server |8000 +|echidna |9000 +|verisim |8080 +|boj-server |7700 +|typell |7800 +|=== + +=== Ecosystem Context + +*Depends on:* - *gossamer* — Desktop backend runtime (Zig + WebKitGTK) - +*verisim* — Persistent storage layer - *typell* — Type intelligence +engine — cross-panel type checking - *boj-server* — MCP server — all +external tool integration + +*Consumed by:* - *idaptik* — Uses PanLL as level editor for game content + +*Related projects:* - *echidna* — Proof engine — formal verification +integration - *hypatia* — Neurosymbolic CI/CD scanning - *panic-attack* +— Security scanning tool - *gitbot-fleet* — Bot orchestration (rhodibot, +echidnabot, etc.) - *proven* — Formally verified alternatives library diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index bc9db095..00000000 --- a/AGENTS.md +++ /dev/null @@ -1,230 +0,0 @@ - - - - -# PanLL — AI Coordination Rules - -> **Auto-generated from `coordination.k9`** — do not edit directly. -> Re-generate with: `deno run --allow-read --allow-write generate.js coordination.k9` -> Source of truth: `coordination.k9` in repository root. - -## Project - -Neurosymbolic IDE built on the Binary Star model — human (symbolic, Panel-L) and machine (neural, Panel-N) orbiting a shared world state (Panel-W). 106 panels, custom TEA runtime, Gossamer desktop backend. - -**Languages:** ReScript, Rust, Elixir, JavaScript -**License:** MPL-2.0 -**Build system:** just -**Runtime:** deno - -## Build Commands - -| Command | Description | -|---------|-------------| -| `just build` | Full build (ReScript + CSS + bundle) | -| `just res` | ReScript compile only | -| `just bundle` | esbuild bundle | -| `just css` | Build CSS | -| `just dev` | Start dev server on port 8000 | -| `just test` | Run test suite (979 tests, 41 suites) | -| `just coverage` | Run tests with coverage | -| `just lint` | Lint ReScript source | -| `just doctor` | Run project health checks | - -## INVARIANTS — Do Not Violate - -These rules are non-negotiable. Violating them will break the project -or contradict deliberate architectural decisions. - -### [CRITICAL] custom-tea-runtime - -**Rule:** The custom TEA runtime in src/tea/ (18 modules) must NEVER be replaced with rescript-tea or any other library - -**Why:** rescript-tea was deliberately evaluated and rejected. The custom TEA runtime handles PanLL-specific needs: Anti-Crash circuit breaking, Vexometer cognitive load adaptation, OrbitalSync multi-panel state coherence, and panel lifecycle management. It is not legacy — it is the architecture. - -### [CRITICAL] no-typescript - -**Rule:** Do not introduce TypeScript files — ReScript is the frontend language - -**Why:** ReScript provides better type safety with less overhead. This is a deliberate, ecosystem-wide decision. - -### [CRITICAL] no-tauri - -**Rule:** Do not introduce Tauri references or dependencies — Gossamer is the desktop backend - -**Why:** PanLL was migrated FROM Tauri 2.0 TO Gossamer. This migration is complete and intentional. - -### [CRITICAL] tea-pattern-only - -**Rule:** All state management uses TEA (Model -> Msg -> Update -> View) — no MVC, Redux, hooks, or other patterns - -**Why:** TEA is foundational to PanLL's architecture. Model.res holds all state, Msg.res defines all messages, Update.res is the state transition kernel. - -### [CRITICAL] all-state-in-model - -**Rule:** ALL application state lives in Model.model — no global mutable state, no module-level state, no window.* state - -**Why:** TEA requires single state tree. Anti-Crash and OrbitalSync depend on this invariant for correctness. - -### [CRITICAL] no-npm-bun - -**Rule:** No npm, Bun, pnpm, or yarn — Deno is the orchestrator - -**Why:** Deno-only build (post panll#65). ReScript and Tailwind run via `npm:` specifiers in `deno.json` — there is no `package.json` and no npm CLI is invoked. Do not reintroduce npm/bun/yarn/pnpm tooling. - -### [CRITICAL] anticrash-validates-all - -**Rule:** Anti-Crash circuit breaker validates ALL neural tokens before symbolic execution — never bypass this - -**Why:** Safety-critical: prevents untrusted neural output from corrupting symbolic state. The validation path exists for a reason. - -### [HIGH] panels-not-panes - -**Rule:** UI elements are called 'panels', NEVER 'panes', 'tabs', or 'windows' - -**Why:** PanLL naming convention — 'panels' is the correct term everywhere in code, docs, and communication - -### [CRITICAL] no-bulk-panel-deletion - -**Rule:** Do not delete more than 2 panel files in a single operation without explicit user approval - -**Why:** 106 panels have complex interdependencies. Bulk deletion can cascade and break OrbitalSync. - -### [HIGH] gossamer-bridge-pattern - -**Rule:** Gossamer commands in src/commands/ are invoke wrappers only — do not put business logic there - -**Why:** Business logic belongs in Update.res. Commands are thin bridges to the Gossamer backend. - -### [CRITICAL] binary-star-model - -**Rule:** The Binary Star architecture (Panel-L symbolic + Panel-N neural + Panel-W world) is deliberate — do not flatten into a single panel type - -**Why:** The three panel types serve fundamentally different roles. This is the core design of PanLL. - -### [CRITICAL] rescript-core-team - -**Rule:** The project owner is on the ReScript core team — do not suggest migrating away from ReScript - -**Why:** ReScript is not a temporary choice. The owner contributes to ReScript itself. - -## Protected Files and Directories - -Do NOT delete, reorganise, or replace these without explicit user approval: - -| Path | Reason | -|------|--------| -| `src/tea/` | Custom TEA runtime — 18 modules. NEVER replace with rescript-tea. | -| `src/Model.res` | Single state tree — all application state lives here | -| `src/Msg.res` | Message type definitions — the TEA message catalogue | -| `src/Update.res` | State transition kernel — ~7500 lines, the heart of PanLL | -| `src/View.res` | Root view renderer | -| `src/App.res` | Application entry point | -| `src/core/` | Core engines — AntiCrash, OrbitalSync, Contractiles, TypeLLEngine, VabEngine | -| `src/components/` | 106 panel views — do not bulk-delete | -| `src/commands/` | Gossamer bridge commands — thin wrappers only | -| `src/modules/` | Module registry + TypeLLService — cross-panel type intelligence | -| `src-gossamer/` | Rust backend (WebKitGTK) — Gossamer desktop integration | -| `beam/` | Elixir/BEAM API layer | -| `tests/` | 979 tests, 41 suites — never delete tests | -| `.machine_readable/` | Canonical location for A2ML state files — MUST stay here | -| `coordination.k9` | This file — source of truth for AI coordination | - -## Architecture Decisions (Deliberate) - -These choices may look unusual but are intentional: - -### gossamer-not-tauri - -**Decision:** Gossamer (Zig + WebKitGTK) is the desktop backend — migration from Tauri 2.0 is complete - -**Why:** Gossamer is the hyperpolymath desktop runtime. Tauri was used previously but replaced. - -**Rejected alternatives:** Tauri 2.0, Electron, native GTK - -### custom-tea-not-rescript-tea - -**Decision:** Custom TEA runtime (src/tea/, 18 modules) instead of the rescript-tea library - -**Why:** PanLL needs Anti-Crash integration, OrbitalSync, Vexometer hooks, and panel lifecycle — none available in rescript-tea - -**Rejected alternatives:** rescript-tea, Redux, MobX, React hooks pattern - -### deno-only-with-npm-specifiers - -**Decision:** Deno orchestrates everything; ReScript and Tailwind run via `npm:` specifiers in `deno.json` - -**Why:** Post panll#65: `package.json` + `package-lock.json` deleted; ReScript compiles via `deno run -A --allow-scripts=npm:rescript npm:rescript@^12.0.0 build`, Tailwind via `deno run -A npm:tailwindcss`. No npm CLI invocation. Do not extend npm's role. - -### binary-star - -**Decision:** Three panel types: Panel-L (symbolic/human), Panel-N (neural/machine), Panel-W (world/shared) - -**Why:** Neurosymbolic architecture requires clear separation of human reasoning, machine inference, and shared world state - -### vexometer-cognitive-load - -**Decision:** Vexometer monitors operator stress and adapts UI detail density - -**Why:** HTI (Human-Tool Interaction) principle — the IDE adapts to the human, not vice versa - -### anticrash-circuit-breaker - -**Decision:** Anti-Crash validates all neural tokens before they enter the symbolic pipeline - -**Why:** Safety boundary between neural and symbolic systems — prevents hallucinated code from corrupting state - -## Do NOT Create - -These files, patterns, or systems must NOT be introduced: - -- ****/*.ts** — TypeScript is banned — use ReScript -- **Dockerfile** — Use Containerfile (Podman, not Docker) -- ****/*.py** — Python is banned — use ReScript, Rust, or Elixir -- **A replacement TEA runtime or state management library** — src/tea/ is the TEA runtime — it is custom, deliberate, and must not be replaced -- **REST API endpoints parallel to existing Groove protocol endpoints** — Groove is the inter-service communication protocol — do not create REST alternatives -- **A new panel type beyond Panel-L, Panel-N, Panel-W** — Binary Star model has exactly three types — adding more would break OrbitalSync -- **Direct Tauri imports or tauri.conf.json** — Tauri migration to Gossamer is complete — do not reintroduce - -## Terminology - -Use the correct terms for this project: - -- Say **"panels"**, NOT "panes", "tabs", "windows" - - PanLL UI elements are always called panels — this is enforced everywhere -- Say **"Binary Star"**, NOT "dual-pane", "split-view", "two-panel" - - The architectural model is Binary Star (Panel-L + Panel-N orbiting Panel-W) -- Say **"Anti-Crash"**, NOT "validator", "sanitizer", "filter" - - The neural token validation system is called Anti-Crash -- Say **"Vexometer"**, NOT "stress meter", "load indicator", "fatigue tracker" - - The cognitive load monitoring system is called Vexometer -- Say **"OrbitalSync"**, NOT "state sync", "panel sync", "sync engine" - - The multi-panel state coherence system is called OrbitalSync - -## Port Assignments - -| Service | Port | -|---------|------| -| dev-server | 8000 | -| echidna | 9000 | -| verisim | 8080 | -| boj-server | 7700 | -| typell | 7800 | - -## Ecosystem Context - -**Depends on:** -- **gossamer** — Desktop backend runtime (Zig + WebKitGTK) -- **verisim** — Persistent storage layer -- **typell** — Type intelligence engine — cross-panel type checking -- **boj-server** — MCP server — all external tool integration - -**Consumed by:** -- **idaptik** — Uses PanLL as level editor for game content - -**Related projects:** -- **echidna** — Proof engine — formal verification integration -- **hypatia** — Neurosymbolic CI/CD scanning -- **panic-attack** — Security scanning tool -- **gitbot-fleet** — Bot orchestration (rhodibot, echidnabot, etc.) -- **proven** — Formally verified alternatives library diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 00000000..1c0a7a69 --- /dev/null +++ b/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 607e3d8c..00000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc new file mode 100644 index 00000000..3ff9df14 --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,413 @@ +== Changelog + +All notable changes to the PanLL eNSAID project will be documented in +this file. + +The format is based on https://keepachangelog.com/en/1.0.0/[Keep a +Changelog], and this project adheres to +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== https://github.com/hyperpolymath/panll/compare/v0.1.0...HEAD[Unreleased] + +==== Changed (2026-05-30 — npm → Deno migration) + +* *`+package.json+` + `+package-lock.json+` deleted.* ReScript and +Tailwind now run via `+npm:+` specifiers in `+deno.json+`: +** ReScript: +`+deno run -A --allow-scripts=npm:rescript npm:rescript@^12.0.0 build+` +(exposed as `+deno task res:build+`) +** Tailwind: `+deno run -A npm:tailwindcss+` (transitional — no +Deno-native drop-in yet) +* *`+setup-node+` removed from CI* in +`+.github/workflows/build-validation.yml+` and +`+.github/workflows/e2e.yml+`; supersedes the `+panll#62+` +`+npm install+` band-aid. See `+panll#65+` for the migration PR. + +==== Changed (2026-05-17 — Tech-debt remediation: lib/bin split) + +* *`+[lib] panll+` crate extracted* — all GTK-free backend logic +(`+http_client+`, `+service_registry+`, `+settings+`, `+identity+`, +`+groove+`, `+llm_coding+`, `+coprocessor+`) moved into a library crate. +`+main.rs+` keeps only `+system_tray+` (depends on `+gossamer_rs+`). +`+cargo test --lib+` now runs the unit suite (23 tests) without linking +libgossamer/GTK/WebKit. +* *`+coprocessor+` wired into the build* — it was orphaned (declared by +no crate root, never compiled). Now part of the lib, with real Zig FFI +dynamic loading via `+libloading 0.8+` (`+dlopen+` + `+copro_init+`, +`+copro_dispatch+`/`+copro_free+`), replacing the previous no-op stubs. + +==== Added (2026-05-17) + +* Service-registry runtime reconfiguration: `+service_list+` and +`+service_set_url+` IPC commands; `+settings_save+` (bulk replace); +`+llm_coding_system_resources+` (host memory + `+/proc/stat+` CPU +sampler). +* Unit + integration tests for `+http_client+`, `+service_registry+`, +`+llm_coding+`, `+coprocessor+`. + +==== Removed (2026-05-17) + +* Speculative, never-referenced scaffolding: `+WorkspaceLock+`, +`+PendingAction+`, `+SpawnRequest.task_list+`, and the vestigial +`+service_register+`/`+service_unregister+` command stubs. +* Stale Tauri references in `+coprocessor+`/`+llm_coding+` comments. + +==== Fixed (2026-05-17) + +* `+docs/TECHNICAL_DEBT.md+` rewritten from a stale 2024-dated +placeholder document into a verified, executed plan; broken +`+docs/ARCHITECTURE.md+` link repointed to +`+docs/architecture/ARCHITECTURE.md+`. +* `+.github/hypatia-rules/panll-v0.2.0-fixes.yml+` reconciled (v1 → v2): +retired 8 false-positive panic-attack rules, kept one precise regression +guard for disabled IPC commands. + +==== Fixed (2024-04-15 — v0.2.0 Panic Attack Remediation) + +* *Critical Build Issues* — Resolved 37 compilation errors and warnings +during panic attack: +** Fixed `+http_client+` import syntax in `+service_registry.rs+` +** Fixed improper `+Result+` handling in `+main.rs+` +** Fixed PathBuf Display trait issues in `+llm_coding/commands.rs+` +** Fixed type mismatches in `+llm_coding/types.rs+` +** Commented out unused modules (`+groove+`, `+settings+`, +`+llm_coding+` commands) +** Fixed result type mismatches in command handlers +* *Type System Fixes* — Resolved structural mismatches: +** Fixed `+ResourceStats+` vs `+ResourceUsage+` type confusion +** Fixed field name mismatches in `+LlmSession+` and `+SpawnRequest+` +** Fixed `+sent_at+` timestamp type (u64 vs String) +** Fixed `+subagent_count+` type conversion (usize to u32) +* *Filesystem Handling* — Fixed path conversion issues: +** Replaced `+PathBuf.to_string()+` with safe `+to_str().unwrap_or("")+` +** Fixed `+DirEntry+` path extraction +** Added proper error handling for filesystem operations +* *Error Handling* — Improved robustness: +** Added proper Result unwrapping patterns +** Fixed command handler return types +** Added bounds checking and fallbacks + +==== Added (2024-04-15 — v0.2.0 Quality Infrastructure) + +* *Hypatia Scanner Rules* — Added 8 new detection rules for automated +code quality: +** `+panll-001+`: Unresolved http_client imports +** `+panll-002+`: Commented out modules +** `+panll-003+`: Improper Gossamer App handling +** `+panll-004+`: PathBuf Display trait misuse +** `+panll-005+`: Command result type mismatches +** `+panll-006+`: Unused documentation comments +** `+panll-007+`: Hardcoded service URLs +** `+panll-008+`: Improper error handling +* *Technical Debt Registry* — Comprehensive documentation of: +** 2 critical issues blocking release +** 4 high priority issues +** 19 medium/low priority issues +** Complete remediation plan and timeline +** Progress tracking (32% complete) +* *GitBot Fleet Configuration* — Automated remediation setup: +** Auto-remediation for 3 rule patterns +** Ticket creation for 5 rule patterns +** Team notifications (backend, devops, qa) +** Integration with existing CI/CD pipeline + +==== Documentation (2024-04-15 — v0.2.0 Handover) + +* *TECHNICAL_DEBT.md* — Complete registry of all known issues +* *Hypatia Rules* — `+.github/hypatia-rules/panll-v0.2.0-fixes.yml+` +* *Updated CHANGELOG.md* — This entry +* *Inline Documentation* — Fixed and updated doc comments throughout + +==== Added (2026-04-07 — Wizard System & Plugin/Panel Creation) + +* *Wizard System* — Complete guided creation workflow for plugins and +panels with 5-step process: +** Select Type (Panel/Plugin) +** Choose Capabilities (with real-time validation) +** Configure Dependencies (version management) +** Setup Security (trust tiers, permissions) +** Review & Generate (validation + minter integration) +* *Template System* — 4 predefined templates for common use cases: +** Basic Panel (ui-rendering, state-management) +** Groove Integration Panel (groove-hard, contractile) +** Data Visualization Plugin (charting, ui-rendering) +** Governance Plugin (contractile, provisioner) +* *Real-Time Validation* — Immediate feedback system with: +** Capability conflict detection (groove-hard vs groove-soft) +** Dependency validation (duplicates, empty fields) +** Security policy enforcement (trust tier permissions) +** Template validation (required fields, structure) +* *Minter Integration* — Command-based generation system: +** `+WizardCmd.generate()+` — Backend generation endpoint +** `+WizardCmd.validateConfig()+` — Pre-generation validation +** Full error handling and result management +* *Testing Suite* — Comprehensive test coverage: +** 4 unit tests (template application, validation rules) +** 2 integration tests (complete workflow, error handling) +** 2 performance benchmarks (template: 0.42ms, validation: 0.18ms) +** 1 accessibility test (WCAG 2.3 compliance) +** 100% pass rate, automated reporting +* *Documentation* — Complete standards documentation: +** `+docs/standards/wizard/WIZARD-STANDARDS.adoc+` — Architecture, +validation, templates +** Performance benchmarks and compliance requirements +** Integration guides and future roadmap + +==== Added (2026-03-29 — CRG D→C Prep) + +* *dogfood-test.sh* — Verifies local backends (Farm, Provenance, +Watcher) return real data for CRG promotion +* *CRG-DOGFOOD-CHECKLIST.md* — Updated: Git blame and Filesystem +backends marked as code-verified + +==== Fixed (2026-03-23 — TEA Crash Recovery) + +* *RuntimeBridge.invoke browser-mode crash* — +`+JsError.throwWithMessage+` threw synchronously instead of returning a +rejected Promise, killing the TEA dispatch loop on the first backend +call in browser mode. Fixed to use `+Promise.reject(new Error(...))+`. +Same fix applied to `+Dialog.openDialog+` and Fs methods. +* *TEA dispatch loop freeze* — Added try/catch around +`+processMessage+`, `+render+`, and `+subscriptions+` in `+Tea_App.res+` +so one thrown exception no longer permanently freezes all event +handling. +* *ReScript build errors* — `+open+` reserved keyword in +`+RuntimeBridge.Dialog+` renamed to `+openDialog+` (propagated to +`+GossamerCmd.res+`, `+RepoLoaderCmd.res+`); `+String.indexOf+` return +type mismatch in `+RuntimeResolver.res+`; duplicate `+detectRuntime+` +symbol renamed to `+currentRuntime+`. +* *Missing panel view cases* — Added 13 placeholder view cases in +`+View.res+` for GSA, Burble, and IDApTIK panels registered in the Clade +system. + +==== Added (2026-03-23 — Diagnostics & Debug API) + +* *`+window.__panll+` debug API* — `+getModel()+`, `+dispatch(msg)+`, +`+snapshot()+` for live browser-console diagnostics. +* *Diagnostic bar* (`+public/index.html+`) — Live message counter, crash +display, click-to-copy snapshot, red Hard Refresh button, cache-busting +import. +* *Back button repositioned* — Moved from top-left (obscuring panel +headers) to top-right as a labelled "`← Back`" pill. +* *Event chain textarea* — Improved placeholder with JSON format +example. + +==== Changed (2026-03-23 — Tauri→Gossamer Migration) + +* *Gossamer-only RuntimeBridge* — Removed all Tauri runtime references +(`+isTauriRuntime+`, `+tauriInvoke+`, `+@tauri-apps+` imports) from +`+RuntimeBridge.res+`. +* *270 commands migrated* — All Tauri invoke commands rewritten for +Gossamer IPC in `+src-gossamer/+`. +* *`+src-tauri/+` deleted* — Replaced by `+src-gossamer/+` with migrated +Rust backend. + +==== Fixed (2026-03-10) + +* *SVG className crash* — `+Tea_Render.res+` was setting +`+el.className+` on SVG elements which throws because +`+SVGAnimatedString+` is read-only. Now uses +`+setAttribute("class", ...)+` for SVG elements. This was causing the +grey screen on startup. + +==== Added (2026-03-10 — Neural Stream Enrichment) + +* *Enriched neural token model* — tokens now carry full provenance +metadata: +** `+source+`: 7 subsystem types (NeuralInference, EchidnaProver, +TypeLLKernel, VeriSimInference, AntiCrashGate, OperatorInput, +OrbitalSync) +** `+category+`: 8 semantic types (Observation, Hypothesis, Deduction, +Abduction, ProofStep, Violation, Correction, Synthesis) +** `+emittedDuring+`: OODA phase tracking (Observe/Orient/Decide/Act) +** `+causedBy+`: causal chain links forming an inference DAG +** `+proofHash+`: optional proof certificate hash +* *OODA phase timeline* — horizontal coloured bar showing phase +distribution across tokens +* *Source distribution bar* — colour-coded breakdown of subsystem +contributions +* *Causal inference graph* — compact DAG display showing how tokens are +causally linked +* *Interactive token filtering* — clickable chips for +source/category/phase, confidence threshold slider, validated-only and +proof-only toggles, clear button, filtered count indicator +* *Menu bar actions wired* — import chain/panic report, reset panels, +preferences, ECHIDNA/provenance panel routing +* *New modules* — Accessibility, Help, MenuBar, ScriptGist, Tiling, +FocusDimming, WindowBridge + +==== Added (2026-03-08 — BoJ Primary Gateway) + +* *BoJ primary gateway routing* — 4 panels now route through BoJ +cartridges via `+bojRouting+` toggle +** Editor Bridge LSP → `+lsp-mcp+`: ConnectLsp, RefreshDiagnostics, +RefreshSymbols +** VeriSimDB → `+database-mcp+`: CheckHealth, SubmitQuery, ListEntities, +SelectEntity, FetchTelemetry, FetchOrchStatus +** VM Inspector DAP → `+dap-mcp+`: StepForward, StepBackward, RunVm +** Build Dashboard BSP → `+bsp-mcp+`: TriggerBuild, RefreshBuildStatus, +RunTests +* *BoJ JSON deserialisers* — `+parseCartridges+`, `+parseTopology+`, +`+parseUmojaStatus+` in BojEngine.res +** CartridgesResult, TopologyResult, UmojaResult handlers now parse real +data (were TODO stubs) +* *FeedbackOTron BoJ context snapshot* — renders connection status, +cartridge counts, last invoke, Umoja status +* *ToggleDryRun* — proper Live↔DryRun toggle in workspace (was one-way +only) +* *Panel Bus pub/sub* — 10 event topics, event envelopes, subscriber +registry (11 defaults), 100-event ring buffer +* *Clade Tier 1-4 system* — protocols, capabilities, dependencies, +isolation, signing, SBOM, sandbox policies + +==== Added (2026-03-08) + +* *Coprocessor control plane* — Phase 1 orchestration of external +compute engines +** Rust backend: `+query_compute_engine+`, `+discover_compute_devices+` +Tauri commands +** Device discovery for Axiom.jl (HTTP), BoJ cartridges, and local +CPU/WASM +** Dashboard UI: discovered devices grid, compute result display, engine +query +** Model: `+computeEngine+`, `+computeDevice+`, `+computeQueryResult+` +types +** Engine: `+parseComputeResult+`, `+parseDevices+`, `+engineLabel+` +helpers +* *Clade permission system UI* — interactive cross-clade reference +control +** Messages: `+SetCladePermission+`, `+RemoveCladePermission+` +** Panel Map tab: permission badges (open/restricted/locked) with +click-to-toggle +** Update handler: uses +`+CladeBrowserEngine.setPermission+`/`+removePermission+` +* *Protocol-Squisher comparison parsing* — `+parseComparison+` function +for schema compatibility JSON +** `+ComparisonResult(Ok(json))+` handler now parses into +`+schemaCompatibilityResult+` +* *Clade metadata extensions* (Tier 1.1-1.4) +** 13 wire protocols: LSP, DAP, BSP, MCP, REST, gRPC, GraphQL, +WebSocket, SSE, TauriIPC, UnixSocket, DBus, Stdio +** 14 typed capabilities: Filesystem, Network, Clipboard, ProcessSpawn, +Shell, Containerised, Streaming, ProofProduction/Consumption, +TypeChecking, SecurityScan, SecretManagement, Visualisation, +SessionRecording +** Dependency graph: `+cladeDependency+` with hard/soft requirements +** Fault isolation levels: None, Soft, Process, Container +* *TypeLL cross-panel wiring* — 8 integration points all live +** VeriSimDB: VCL type checking on query submit +** Protocol-Squisher: schema type checking on analysis +** My-Lang: dialect-aware type checking on compile +** Anti-Crash: type-level token validation with constraint expressions +** Pane-L: constraint type inference on editor changes +** BoJ: cartridge ABI type checking on invoke +** ECHIDNA: proof obligation generation on proof submit +* *My-Lang LSP Rust backend* — `+mylang_lsp_connect+` and +`+mylang_lsp_diagnostics+` Tauri commands +* *Test coverage: 979 Deno + 28 Rust tests* across 41 suites (was 406 +across 27) +** New engine suites: TypeLL, Protocol-Squisher, My-Lang, BoJ, +Coprocessors, Valence Shell, Game Preview, VM Inspector, Network +Topology, Level Architect, Tentacles, CloudGuard, Plaza, Minter, Aerie, +AI +* *Rust test gate in CI* — `+cargo test+` added to build-validation.yml +* *.well-known/security.txt* — RFC 9116 security contact + +==== Added (2026-02-12) + +* *Tauri Backend Implementation*: All 3 backend commands now fully +implemented +** `+validate_inference+`: Real constraint parsing with forbidden +patterns and type checking +** `+get_vexation_index+`: Decay-based vexation tracking with 2-minute +sliding window +** `+submit_feedback+`: JSON file persistence with timestamps +* *OrbitalSync Module*: Full synchronization implementation wired into +update loop +** Divergence calculation between Pane-L and Pane-N content +** Stability tracking with latency penalty computation +** Drift aura color indication (indigo/violet/amber) +* *Contractiles Module*: Adaptive contract evaluation wired into update +loop +** Contract enforcement levels (Strict/Warn/Adaptive) +** Orbital stability and vexation ceiling contracts +** Contract adaptation based on system state +* *AntiCrash Validation*: Real constraint validation logic +** Type constraint checking with reserved keyword detection +** Logic constraint validation with contradiction detection +** Security constraint checking for suspicious patterns +* *ARIA Accessibility*: Complete accessibility attribute support +** 5 new ARIA functions in Tea_Vdom (ariaLabel, ariaLive, ariaExpanded, +ariaHidden, role) +** 12 ARIA attributes across 5 components (PaneL, PaneN, PaneW, +Vexometer, FeedbackOTron) +* *VDOM Diffing*: Efficient virtual DOM diffing implementation +** `+diff()+` function for comparing old and new VDOMs +** `+patch()+` and `+applyPatch()+` for minimal DOM updates +** `+previousVdom+` tracking in renderState +* *Test Coverage*: 33+ new tests across 6 test suites +** OrbitalSync: 7 tests (hash, divergence, stability, aura color) +** Contractiles: 5 tests (defaults, contract evaluation) +** Update: 11 tests (pane updates, vexometer, view, autosave) +** EventChain: +5 edge case tests (empty, invalid, coercion) +** Storage: +5 round-trip tests (persistence, clear/load) +** AntiCrash: 6 validation tests + +==== Changed (2026-02-12) + +* *ReScript Configuration*: Changed module format from `+es6+` to +`+es6-global+` for Tauri compatibility +* *Documentation*: Updated completion percentage from 95% to honest 80% +** README.adoc: Updated badges (80% complete, 36+ passing tests) +** ROADMAP.adoc: Updated status and marked features complete +** STATE.scm: Updated focus, summary, and session history +* *Build Performance*: ReScript compilation now completes in 109ms +* *Model Types*: Moved syncState and contractile types to Model.res to +break circular dependencies + +==== Removed (2026-02-12) + +* Duplicate subscription files (src/Subscriptions.res, +src/subscriptions/Keyboard.res) + +==== Fixed (2026-02-12) + +* Circular dependency between OrbitalSync/Contractiles and Model modules +* Type inference issues with record literals (added explicit type +annotations) +* Array API usage (replaced non-existent `+Array.makeBy+` with +`+Array.fromInitializer+`) +* Unused variable warnings (prefixed with `+_+`) +* ReScript compilation errors + +=== https://github.com/hyperpolymath/panll/compare/v0.0.1...v0.1.0[0.1.0] - 2026-02-09 + +==== Added + +* Custom TEA (The Elm Architecture) implementation +* Three-pane parallel layout (Pane-L, Pane-N, Pane-W) +* Tauri 2.0 backend with command bindings +* Event-chain import from panic-attack +* Anti-Crash token gating +* Vexometer component +* Feedback-O-Tron component +* 33 passing tests with Deno +* RSR compliance (AI manifest, SCM files) + +==== Changed + +* Migrated from npm to Deno for test execution +* Deferred official rescript-tea migration to v0.2.0 + +=== https://github.com/hyperpolymath/panll/releases/tag/v0.0.1[0.0.1] - 2026-02-07 + +==== Added + +* Initial project setup +* Basic ReScript configuration +* Tauri project scaffolding +* .machine_readable/ directory with 6 SCM files +** STATE.scm, META.scm, ECOSYSTEM.scm +** AGENTIC.scm, NEUROSYM.scm, PLAYBOOK.scm +* AI manifest (0-AI-MANIFEST.a2ml) +* Documentation structure diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index f288b594..00000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,305 +0,0 @@ -# Changelog - -All notable changes to the PanLL eNSAID project will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Changed (2026-05-30 — npm → Deno migration) -- **`package.json` + `package-lock.json` deleted.** ReScript and Tailwind now - run via `npm:` specifiers in `deno.json`: - - ReScript: `deno run -A --allow-scripts=npm:rescript npm:rescript@^12.0.0 build` - (exposed as `deno task res:build`) - - Tailwind: `deno run -A npm:tailwindcss` (transitional — no Deno-native - drop-in yet) -- **`setup-node` removed from CI** in `.github/workflows/build-validation.yml` - and `.github/workflows/e2e.yml`; supersedes the `panll#62` `npm install` - band-aid. See `panll#65` for the migration PR. - -### Changed (2026-05-17 — Tech-debt remediation: lib/bin split) -- **`[lib] panll` crate extracted** — all GTK-free backend logic - (`http_client`, `service_registry`, `settings`, `identity`, `groove`, - `llm_coding`, `coprocessor`) moved into a library crate. `main.rs` keeps - only `system_tray` (depends on `gossamer_rs`). `cargo test --lib` now runs - the unit suite (23 tests) without linking libgossamer/GTK/WebKit. -- **`coprocessor` wired into the build** — it was orphaned (declared by no - crate root, never compiled). Now part of the lib, with real Zig FFI - dynamic loading via `libloading 0.8` (`dlopen` + `copro_init`, - `copro_dispatch`/`copro_free`), replacing the previous no-op stubs. - -### Added (2026-05-17) -- Service-registry runtime reconfiguration: `service_list` and - `service_set_url` IPC commands; `settings_save` (bulk replace); - `llm_coding_system_resources` (host memory + `/proc/stat` CPU sampler). -- Unit + integration tests for `http_client`, `service_registry`, - `llm_coding`, `coprocessor`. - -### Removed (2026-05-17) -- Speculative, never-referenced scaffolding: `WorkspaceLock`, - `PendingAction`, `SpawnRequest.task_list`, and the vestigial - `service_register`/`service_unregister` command stubs. -- Stale Tauri references in `coprocessor`/`llm_coding` comments. - -### Fixed (2026-05-17) -- `docs/TECHNICAL_DEBT.md` rewritten from a stale 2024-dated placeholder - document into a verified, executed plan; broken `docs/ARCHITECTURE.md` - link repointed to `docs/architecture/ARCHITECTURE.md`. -- `.github/hypatia-rules/panll-v0.2.0-fixes.yml` reconciled (v1 → v2): - retired 8 false-positive panic-attack rules, kept one precise regression - guard for disabled IPC commands. - -### Fixed (2024-04-15 — v0.2.0 Panic Attack Remediation) -- **Critical Build Issues** — Resolved 37 compilation errors and warnings during panic attack: - - Fixed `http_client` import syntax in `service_registry.rs` - - Fixed improper `Result` handling in `main.rs` - - Fixed PathBuf Display trait issues in `llm_coding/commands.rs` - - Fixed type mismatches in `llm_coding/types.rs` - - Commented out unused modules (`groove`, `settings`, `llm_coding` commands) - - Fixed result type mismatches in command handlers - -- **Type System Fixes** — Resolved structural mismatches: - - Fixed `ResourceStats` vs `ResourceUsage` type confusion - - Fixed field name mismatches in `LlmSession` and `SpawnRequest` - - Fixed `sent_at` timestamp type (u64 vs String) - - Fixed `subagent_count` type conversion (usize to u32) - -- **Filesystem Handling** — Fixed path conversion issues: - - Replaced `PathBuf.to_string()` with safe `to_str().unwrap_or("")` - - Fixed `DirEntry` path extraction - - Added proper error handling for filesystem operations - -- **Error Handling** — Improved robustness: - - Added proper Result unwrapping patterns - - Fixed command handler return types - - Added bounds checking and fallbacks - -### Added (2024-04-15 — v0.2.0 Quality Infrastructure) -- **Hypatia Scanner Rules** — Added 8 new detection rules for automated code quality: - - `panll-001`: Unresolved http_client imports - - `panll-002`: Commented out modules - - `panll-003`: Improper Gossamer App handling - - `panll-004`: PathBuf Display trait misuse - - `panll-005`: Command result type mismatches - - `panll-006`: Unused documentation comments - - `panll-007`: Hardcoded service URLs - - `panll-008`: Improper error handling - -- **Technical Debt Registry** — Comprehensive documentation of: - - 2 critical issues blocking release - - 4 high priority issues - - 19 medium/low priority issues - - Complete remediation plan and timeline - - Progress tracking (32% complete) - -- **GitBot Fleet Configuration** — Automated remediation setup: - - Auto-remediation for 3 rule patterns - - Ticket creation for 5 rule patterns - - Team notifications (backend, devops, qa) - - Integration with existing CI/CD pipeline - -### Documentation (2024-04-15 — v0.2.0 Handover) -- **TECHNICAL_DEBT.md** — Complete registry of all known issues -- **Hypatia Rules** — `.github/hypatia-rules/panll-v0.2.0-fixes.yml` -- **Updated CHANGELOG.md** — This entry -- **Inline Documentation** — Fixed and updated doc comments throughout - -### Added (2026-04-07 — Wizard System & Plugin/Panel Creation) -- **Wizard System** — Complete guided creation workflow for plugins and panels with 5-step process: - - Select Type (Panel/Plugin) - - Choose Capabilities (with real-time validation) - - Configure Dependencies (version management) - - Setup Security (trust tiers, permissions) - - Review & Generate (validation + minter integration) -- **Template System** — 4 predefined templates for common use cases: - - Basic Panel (ui-rendering, state-management) - - Groove Integration Panel (groove-hard, contractile) - - Data Visualization Plugin (charting, ui-rendering) - - Governance Plugin (contractile, provisioner) -- **Real-Time Validation** — Immediate feedback system with: - - Capability conflict detection (groove-hard vs groove-soft) - - Dependency validation (duplicates, empty fields) - - Security policy enforcement (trust tier permissions) - - Template validation (required fields, structure) -- **Minter Integration** — Command-based generation system: - - `WizardCmd.generate()` — Backend generation endpoint - - `WizardCmd.validateConfig()` — Pre-generation validation - - Full error handling and result management -- **Testing Suite** — Comprehensive test coverage: - - 4 unit tests (template application, validation rules) - - 2 integration tests (complete workflow, error handling) - - 2 performance benchmarks (template: 0.42ms, validation: 0.18ms) - - 1 accessibility test (WCAG 2.3 compliance) - - 100% pass rate, automated reporting -- **Documentation** — Complete standards documentation: - - `docs/standards/wizard/WIZARD-STANDARDS.adoc` — Architecture, validation, templates - - Performance benchmarks and compliance requirements - - Integration guides and future roadmap - -### Added (2026-03-29 — CRG D→C Prep) -- **dogfood-test.sh** — Verifies local backends (Farm, Provenance, Watcher) return real data for CRG promotion -- **CRG-DOGFOOD-CHECKLIST.md** — Updated: Git blame and Filesystem backends marked as code-verified - -### Fixed (2026-03-23 — TEA Crash Recovery) -- **RuntimeBridge.invoke browser-mode crash** — `JsError.throwWithMessage` threw synchronously instead of returning a rejected Promise, killing the TEA dispatch loop on the first backend call in browser mode. Fixed to use `Promise.reject(new Error(...))`. Same fix applied to `Dialog.openDialog` and Fs methods. -- **TEA dispatch loop freeze** — Added try/catch around `processMessage`, `render`, and `subscriptions` in `Tea_App.res` so one thrown exception no longer permanently freezes all event handling. -- **ReScript build errors** — `open` reserved keyword in `RuntimeBridge.Dialog` renamed to `openDialog` (propagated to `GossamerCmd.res`, `RepoLoaderCmd.res`); `String.indexOf` return type mismatch in `RuntimeResolver.res`; duplicate `detectRuntime` symbol renamed to `currentRuntime`. -- **Missing panel view cases** — Added 13 placeholder view cases in `View.res` for GSA, Burble, and IDApTIK panels registered in the Clade system. - -### Added (2026-03-23 — Diagnostics & Debug API) -- **`window.__panll` debug API** — `getModel()`, `dispatch(msg)`, `snapshot()` for live browser-console diagnostics. -- **Diagnostic bar** (`public/index.html`) — Live message counter, crash display, click-to-copy snapshot, red Hard Refresh button, cache-busting import. -- **Back button repositioned** — Moved from top-left (obscuring panel headers) to top-right as a labelled "← Back" pill. -- **Event chain textarea** — Improved placeholder with JSON format example. - -### Changed (2026-03-23 — Tauri→Gossamer Migration) -- **Gossamer-only RuntimeBridge** — Removed all Tauri runtime references (`isTauriRuntime`, `tauriInvoke`, `@tauri-apps` imports) from `RuntimeBridge.res`. -- **270 commands migrated** — All Tauri invoke commands rewritten for Gossamer IPC in `src-gossamer/`. -- **`src-tauri/` deleted** — Replaced by `src-gossamer/` with migrated Rust backend. - -### Fixed (2026-03-10) -- **SVG className crash** — `Tea_Render.res` was setting `el.className` on SVG elements which throws because `SVGAnimatedString` is read-only. Now uses `setAttribute("class", ...)` for SVG elements. This was causing the grey screen on startup. - -### Added (2026-03-10 — Neural Stream Enrichment) -- **Enriched neural token model** — tokens now carry full provenance metadata: - - `source`: 7 subsystem types (NeuralInference, EchidnaProver, TypeLLKernel, VeriSimInference, AntiCrashGate, OperatorInput, OrbitalSync) - - `category`: 8 semantic types (Observation, Hypothesis, Deduction, Abduction, ProofStep, Violation, Correction, Synthesis) - - `emittedDuring`: OODA phase tracking (Observe/Orient/Decide/Act) - - `causedBy`: causal chain links forming an inference DAG - - `proofHash`: optional proof certificate hash -- **OODA phase timeline** — horizontal coloured bar showing phase distribution across tokens -- **Source distribution bar** — colour-coded breakdown of subsystem contributions -- **Causal inference graph** — compact DAG display showing how tokens are causally linked -- **Interactive token filtering** — clickable chips for source/category/phase, confidence threshold slider, validated-only and proof-only toggles, clear button, filtered count indicator -- **Menu bar actions wired** — import chain/panic report, reset panels, preferences, ECHIDNA/provenance panel routing -- **New modules** — Accessibility, Help, MenuBar, ScriptGist, Tiling, FocusDimming, WindowBridge - -### Added (2026-03-08 — BoJ Primary Gateway) -- **BoJ primary gateway routing** — 4 panels now route through BoJ cartridges via `bojRouting` toggle - - Editor Bridge LSP → `lsp-mcp`: ConnectLsp, RefreshDiagnostics, RefreshSymbols - - VeriSimDB → `database-mcp`: CheckHealth, SubmitQuery, ListEntities, SelectEntity, FetchTelemetry, FetchOrchStatus - - VM Inspector DAP → `dap-mcp`: StepForward, StepBackward, RunVm - - Build Dashboard BSP → `bsp-mcp`: TriggerBuild, RefreshBuildStatus, RunTests -- **BoJ JSON deserialisers** — `parseCartridges`, `parseTopology`, `parseUmojaStatus` in BojEngine.res - - CartridgesResult, TopologyResult, UmojaResult handlers now parse real data (were TODO stubs) -- **FeedbackOTron BoJ context snapshot** — renders connection status, cartridge counts, last invoke, Umoja status -- **ToggleDryRun** — proper Live↔DryRun toggle in workspace (was one-way only) -- **Panel Bus pub/sub** — 10 event topics, event envelopes, subscriber registry (11 defaults), 100-event ring buffer -- **Clade Tier 1-4 system** — protocols, capabilities, dependencies, isolation, signing, SBOM, sandbox policies - -### Added (2026-03-08) -- **Coprocessor control plane** — Phase 1 orchestration of external compute engines - - Rust backend: `query_compute_engine`, `discover_compute_devices` Tauri commands - - Device discovery for Axiom.jl (HTTP), BoJ cartridges, and local CPU/WASM - - Dashboard UI: discovered devices grid, compute result display, engine query - - Model: `computeEngine`, `computeDevice`, `computeQueryResult` types - - Engine: `parseComputeResult`, `parseDevices`, `engineLabel` helpers -- **Clade permission system UI** — interactive cross-clade reference control - - Messages: `SetCladePermission`, `RemoveCladePermission` - - Panel Map tab: permission badges (open/restricted/locked) with click-to-toggle - - Update handler: uses `CladeBrowserEngine.setPermission`/`removePermission` -- **Protocol-Squisher comparison parsing** — `parseComparison` function for schema compatibility JSON - - `ComparisonResult(Ok(json))` handler now parses into `schemaCompatibilityResult` -- **Clade metadata extensions** (Tier 1.1-1.4) - - 13 wire protocols: LSP, DAP, BSP, MCP, REST, gRPC, GraphQL, WebSocket, SSE, TauriIPC, UnixSocket, DBus, Stdio - - 14 typed capabilities: Filesystem, Network, Clipboard, ProcessSpawn, Shell, Containerised, Streaming, ProofProduction/Consumption, TypeChecking, SecurityScan, SecretManagement, Visualisation, SessionRecording - - Dependency graph: `cladeDependency` with hard/soft requirements - - Fault isolation levels: None, Soft, Process, Container -- **TypeLL cross-panel wiring** — 8 integration points all live - - VeriSimDB: VCL type checking on query submit - - Protocol-Squisher: schema type checking on analysis - - My-Lang: dialect-aware type checking on compile - - Anti-Crash: type-level token validation with constraint expressions - - Pane-L: constraint type inference on editor changes - - BoJ: cartridge ABI type checking on invoke - - ECHIDNA: proof obligation generation on proof submit -- **My-Lang LSP Rust backend** — `mylang_lsp_connect` and `mylang_lsp_diagnostics` Tauri commands -- **Test coverage: 979 Deno + 28 Rust tests** across 41 suites (was 406 across 27) - - New engine suites: TypeLL, Protocol-Squisher, My-Lang, BoJ, Coprocessors, Valence Shell, Game Preview, VM Inspector, Network Topology, Level Architect, Tentacles, CloudGuard, Plaza, Minter, Aerie, AI -- **Rust test gate in CI** — `cargo test` added to build-validation.yml -- **.well-known/security.txt** — RFC 9116 security contact - -### Added (2026-02-12) -- **Tauri Backend Implementation**: All 3 backend commands now fully implemented - - `validate_inference`: Real constraint parsing with forbidden patterns and type checking - - `get_vexation_index`: Decay-based vexation tracking with 2-minute sliding window - - `submit_feedback`: JSON file persistence with timestamps -- **OrbitalSync Module**: Full synchronization implementation wired into update loop - - Divergence calculation between Pane-L and Pane-N content - - Stability tracking with latency penalty computation - - Drift aura color indication (indigo/violet/amber) -- **Contractiles Module**: Adaptive contract evaluation wired into update loop - - Contract enforcement levels (Strict/Warn/Adaptive) - - Orbital stability and vexation ceiling contracts - - Contract adaptation based on system state -- **AntiCrash Validation**: Real constraint validation logic - - Type constraint checking with reserved keyword detection - - Logic constraint validation with contradiction detection - - Security constraint checking for suspicious patterns -- **ARIA Accessibility**: Complete accessibility attribute support - - 5 new ARIA functions in Tea_Vdom (ariaLabel, ariaLive, ariaExpanded, ariaHidden, role) - - 12 ARIA attributes across 5 components (PaneL, PaneN, PaneW, Vexometer, FeedbackOTron) -- **VDOM Diffing**: Efficient virtual DOM diffing implementation - - `diff()` function for comparing old and new VDOMs - - `patch()` and `applyPatch()` for minimal DOM updates - - `previousVdom` tracking in renderState -- **Test Coverage**: 33+ new tests across 6 test suites - - OrbitalSync: 7 tests (hash, divergence, stability, aura color) - - Contractiles: 5 tests (defaults, contract evaluation) - - Update: 11 tests (pane updates, vexometer, view, autosave) - - EventChain: +5 edge case tests (empty, invalid, coercion) - - Storage: +5 round-trip tests (persistence, clear/load) - - AntiCrash: 6 validation tests - -### Changed (2026-02-12) -- **ReScript Configuration**: Changed module format from `es6` to `es6-global` for Tauri compatibility -- **Documentation**: Updated completion percentage from 95% to honest 80% - - README.adoc: Updated badges (80% complete, 36+ passing tests) - - ROADMAP.adoc: Updated status and marked features complete - - STATE.scm: Updated focus, summary, and session history -- **Build Performance**: ReScript compilation now completes in 109ms -- **Model Types**: Moved syncState and contractile types to Model.res to break circular dependencies - -### Removed (2026-02-12) -- Duplicate subscription files (src/Subscriptions.res, src/subscriptions/Keyboard.res) - -### Fixed (2026-02-12) -- Circular dependency between OrbitalSync/Contractiles and Model modules -- Type inference issues with record literals (added explicit type annotations) -- Array API usage (replaced non-existent `Array.makeBy` with `Array.fromInitializer`) -- Unused variable warnings (prefixed with `_`) -- ReScript compilation errors - -## [0.1.0] - 2026-02-09 - -### Added -- Custom TEA (The Elm Architecture) implementation -- Three-pane parallel layout (Pane-L, Pane-N, Pane-W) -- Tauri 2.0 backend with command bindings -- Event-chain import from panic-attack -- Anti-Crash token gating -- Vexometer component -- Feedback-O-Tron component -- 33 passing tests with Deno -- RSR compliance (AI manifest, SCM files) - -### Changed -- Migrated from npm to Deno for test execution -- Deferred official rescript-tea migration to v0.2.0 - -## [0.0.1] - 2026-02-07 - -### Added -- Initial project setup -- Basic ReScript configuration -- Tauri project scaffolding -- .machine_readable/ directory with 6 SCM files - - STATE.scm, META.scm, ECOSYSTEM.scm - - AGENTIC.scm, NEUROSYM.scm, PLAYBOOK.scm -- AI manifest (0-AI-MANIFEST.a2ml) -- Documentation structure - -[Unreleased]: https://github.com/hyperpolymath/panll/compare/v0.1.0...HEAD -[0.1.0]: https://github.com/hyperpolymath/panll/compare/v0.0.1...v0.1.0 -[0.0.1]: https://github.com/hyperpolymath/panll/releases/tag/v0.0.1 diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 00000000..7fafb70a --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,338 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +Panll a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, +gender identity and expression, level of experience, education, +socio-economic status, nationality, personal appearance, race, caste, +colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |\{\{CONDUCT_EMAIL}} |Detailed reports, sensitive matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *\{\{RESPONSE_TIME}}* +. The \{\{CONDUCT_TEAM}} will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a \{\{CONDUCT_TEAM}} member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The \{\{CONDUCT_TEAM}} will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* \{\{CONDUCT_EMAIL}} with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different \{\{CONDUCT_TEAM}} member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a https://github.com/hyperpolymath/panll/discussions[Discussion] +(for general questions) +* Email \{\{CONDUCT_EMAIL}} (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index 74625b4c..00000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,327 +0,0 @@ -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in Panll a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | {{CONDUCT_EMAIL}} | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **{{RESPONSE_TIME}}** -2. The {{CONDUCT_TEAM}} will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a {{CONDUCT_TEAM}} member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The {{CONDUCT_TEAM}} will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** {{CONDUCT_EMAIL}} with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different {{CONDUCT_TEAM}} member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://github.com/hyperpolymath/panll/discussions) (for general questions) -- Email {{CONDUCT_EMAIL}} (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 00000000..14ccaa9a --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,174 @@ +== Contributing to PanLL + +=== Why These Tools? + +Before you dive in, it helps to understand _why_ PanLL uses the stack it +does. These aren’t arbitrary preferences — they’re lessons learned from +building a 14-panel stateful application. + +*AffineScript instead of TypeScript* — PanLL has 26,000+ lines of state +management across 14 panels. TypeScript’s structural type system means +`+any+` leaks are always one cast away, and discriminated unions require +manual type guards that are easy to forget. ReScript’s sound type system +means if it compiles, the types are correct — no escape hatches, no +`+as unknown as+`, no runtime type errors. Exhaustive pattern matching +on variant types caught dozens of "`missing case`" bugs during the panel +expansion. See https://rescript-lang.org[rescript-lang.org]. + +*Rust + Gossamer instead of Electron* — PanLL’s release binary is ~5 MB. +An equivalent Electron app would be 100+ MB (shipping an entire +Chromium). The Rust backend runs through Gossamer (Zig + WebKitGTK), a +lightweight container-friendly webview shell. Filesystem watching, git +blame parsing, and HTTP clients run with no garbage collector pauses — +important when 106 panels are subscribed to live events. PanLL +originally used Tauri 2.0 but migrated to Gossamer for better container +support and tighter integration with the hyperpolymath stack. + +*Deno instead of npm/Node* — No `+node_modules+` directory (1,200+ +transitive deps for a typical Node project). Built-in test runner. +Secure-by-default permissions. ReScript and Tailwind run via `+npm:+` +specifiers in `+deno.json+`; there is no `+package.json+` and no npm CLI +is invoked. + +*Elixir/BEAM for middleware* — BEAM’s supervision trees mean a crashing +backend connection restarts itself without taking down the whole panel +surface. Pattern matching on messages is the same philosophy as +ReScript’s TEA on the frontend. + +*Julia for data processing* — When batch analysis needs actual numeric +performance. Python’s GIL means "`import numpy and pray`"; Julia’s +multiple dispatch compiles to LLVM native code for every combination of +argument types. + +If you’re coming from TypeScript/React, the biggest mental shift is TEA +(The Elm Architecture): state changes are pure functions, side effects +are commands, and the compiler enforces exhaustiveness everywhere. It’s +more explicit than hooks, but after the first day you’ll wonder why you +ever tolerated `+useEffect+`. + +''''' + +=== Getting Started + +[source,bash] +---- +# Clone the repository +git clone https://github.com/hyperpolymath/panll.git +cd panll + +# Using Nix (recommended for reproducibility) +nix develop + +# Or using toolbox/distrobox +toolbox create panll-dev +toolbox enter panll-dev +# Install dependencies manually + +# Verify setup +just check # or: cargo check / mix compile / etc. +just test # Run test suite +---- + +==== Repository Structure + +.... +panll/ +├── src/ # Source code (Perimeter 1-2) +├── lib/ # Library code (Perimeter 1-2) +├── extensions/ # Extensions (Perimeter 2) +├── plugins/ # Plugins (Perimeter 2) +├── tools/ # Tooling (Perimeter 2) +├── docs/ # Documentation (Perimeter 3) +│ ├── architecture/ # ADRs, specs (Perimeter 2) +│ └── proposals/ # RFCs (Perimeter 3) +├── examples/ # Examples (Perimeter 3) +├── spec/ # Spec tests (Perimeter 3) +├── tests/ # Test suite (Perimeter 2-3) +├── .well-known/ # Protocol files (Perimeter 1-3) +├── .github/ # GitHub config (Perimeter 1) +│ ├── ISSUE_TEMPLATE/ +│ └── workflows/ +├── CHANGELOG.md +├── CODE_OF_CONDUCT.md +├── CONTRIBUTING.md # This file +├── GOVERNANCE.md +├── LICENSE +├── MAINTAINERS.md +├── README.adoc +├── SECURITY.md +├── flake.nix # Nix flake (Perimeter 1) +└── Justfile # Task runner (Perimeter 1) +.... + +''''' + +=== How to Contribute + +==== Reporting Bugs + +*Before reporting*: 1. Search existing issues 2. Check if it’s already +fixed in `+main+` 3. Determine which perimeter the bug affects + +*When reporting*: + +Use the link:.github/ISSUE_TEMPLATE/bug_report.md[bug report template] +and include: + +* Clear, descriptive title +* Environment details (OS, versions, toolchain) +* Steps to reproduce +* Expected vs actual behaviour +* Logs, screenshots, or minimal reproduction + +==== Suggesting Features + +*Before suggesting*: 1. Check the link:ROADMAP.md[roadmap] if available +2. Search existing issues and discussions 3. Consider which perimeter +the feature belongs to + +*When suggesting*: + +Use the link:.github/ISSUE_TEMPLATE/feature_request.md[feature request +template] and include: + +* Problem statement (what pain point does this solve?) +* Proposed solution +* Alternatives considered +* Which perimeter this affects + +==== Your First Contribution + +Look for issues labelled: + +* https://github.com/hyperpolymath/panll/labels/good%20first%20issue[`+good first issue+`] +— Simple Perimeter 3 tasks +* https://github.com/hyperpolymath/panll/labels/help%20wanted[`+help wanted+`] +— Community help needed +* https://github.com/hyperpolymath/panll/labels/documentation[`+documentation+`] +— Docs improvements +* https://github.com/hyperpolymath/panll/labels/perimeter-3[`+perimeter-3+`] +— Community sandbox scope + +''''' + +=== Development Workflow + +==== Branch Naming + +.... +docs/short-description # Documentation (P3) +test/what-added # Test additions (P3) +feat/short-description # New features (P2) +fix/issue-number-description # Bug fixes (P2) +refactor/what-changed # Code improvements (P2) +security/what-fixed # Security fixes (P1-2) +.... + +==== Commit Messages + +We follow https://www.conventionalcommits.org/[Conventional Commits]: +``` (): + +{empty}[optional body] + +{empty}[optional footer] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 97f18eba..00000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,165 +0,0 @@ - - -# Contributing to PanLL - -## Why These Tools? - -Before you dive in, it helps to understand _why_ PanLL uses the stack it does. -These aren't arbitrary preferences — they're lessons learned from building a -14-panel stateful application. - -**AffineScript instead of TypeScript** — PanLL has 26,000+ lines of state management -across 14 panels. TypeScript's structural type system means `any` leaks are -always one cast away, and discriminated unions require manual type guards that -are easy to forget. ReScript's sound type system means if it compiles, the types -are correct — no escape hatches, no `as unknown as`, no runtime type errors. -Exhaustive pattern matching on variant types caught dozens of "missing case" bugs -during the panel expansion. See [rescript-lang.org](https://rescript-lang.org). - -**Rust + Gossamer instead of Electron** — PanLL's release binary is ~5 MB. An -equivalent Electron app would be 100+ MB (shipping an entire Chromium). The Rust -backend runs through Gossamer (Zig + WebKitGTK), a lightweight container-friendly -webview shell. Filesystem watching, git blame parsing, and HTTP clients run with -no garbage collector pauses — important when 106 panels are subscribed to live -events. PanLL originally used Tauri 2.0 but migrated to Gossamer for better -container support and tighter integration with the hyperpolymath stack. - -**Deno instead of npm/Node** — No `node_modules` directory (1,200+ transitive -deps for a typical Node project). Built-in test runner. Secure-by-default -permissions. ReScript and Tailwind run via `npm:` specifiers in `deno.json`; -there is no `package.json` and no npm CLI is invoked. - -**Elixir/BEAM for middleware** — BEAM's supervision trees mean a crashing backend -connection restarts itself without taking down the whole panel surface. Pattern -matching on messages is the same philosophy as ReScript's TEA on the frontend. - -**Julia for data processing** — When batch analysis needs actual numeric -performance. Python's GIL means "import numpy and pray"; Julia's multiple -dispatch compiles to LLVM native code for every combination of argument types. - -If you're coming from TypeScript/React, the biggest mental shift is TEA (The Elm -Architecture): state changes are pure functions, side effects are commands, and -the compiler enforces exhaustiveness everywhere. It's more explicit than hooks, -but after the first day you'll wonder why you ever tolerated `useEffect`. - ---- - -## Getting Started - -```bash -# Clone the repository -git clone https://github.com/hyperpolymath/panll.git -cd panll - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create panll-dev -toolbox enter panll-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -panll/ -├── src/ # Source code (Perimeter 1-2) -├── lib/ # Library code (Perimeter 1-2) -├── extensions/ # Extensions (Perimeter 2) -├── plugins/ # Plugins (Perimeter 2) -├── tools/ # Tooling (Perimeter 2) -├── docs/ # Documentation (Perimeter 3) -│ ├── architecture/ # ADRs, specs (Perimeter 2) -│ └── proposals/ # RFCs (Perimeter 3) -├── examples/ # Examples (Perimeter 3) -├── spec/ # Spec tests (Perimeter 3) -├── tests/ # Test suite (Perimeter 2-3) -├── .well-known/ # Protocol files (Perimeter 1-3) -├── .github/ # GitHub config (Perimeter 1) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── GOVERNANCE.md -├── LICENSE -├── MAINTAINERS.md -├── README.adoc -├── SECURITY.md -├── flake.nix # Nix flake (Perimeter 1) -└── Justfile # Task runner (Perimeter 1) -``` - ---- - -## How to Contribute - -### Reporting Bugs - -**Before reporting**: -1. Search existing issues -2. Check if it's already fixed in `main` -3. Determine which perimeter the bug affects - -**When reporting**: - -Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: - -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour -- Logs, screenshots, or minimal reproduction - -### Suggesting Features - -**Before suggesting**: -1. Check the [roadmap](ROADMAP.md) if available -2. Search existing issues and discussions -3. Consider which perimeter the feature belongs to - -**When suggesting**: - -Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: - -- Problem statement (what pain point does this solve?) -- Proposed solution -- Alternatives considered -- Which perimeter this affects - -### Your First Contribution - -Look for issues labelled: - -- [`good first issue`](https://github.com/hyperpolymath/panll/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/panll/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/panll/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/panll/labels/perimeter-3) — Community sandbox scope - ---- - -## Development Workflow - -### Branch Naming -``` -docs/short-description # Documentation (P3) -test/what-added # Test additions (P3) -feat/short-description # New features (P2) -fix/issue-number-description # Bug fixes (P2) -refactor/what-changed # Code improvements (P2) -security/what-fixed # Security fixes (P1-2) -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): -``` -(): - -[optional body] - -[optional footer] diff --git a/DISCIPLINE_ANALYZERS_PLAN.md b/DISCIPLINE_ANALYZERS_PLAN.adoc similarity index 86% rename from DISCIPLINE_ANALYZERS_PLAN.md rename to DISCIPLINE_ANALYZERS_PLAN.adoc index d10de972..b4ad84ac 100644 --- a/DISCIPLINE_ANALYZERS_PLAN.md +++ b/DISCIPLINE_ANALYZERS_PLAN.adoc @@ -1,34 +1,39 @@ -# Discipline-Specific Security Analyzers +== Discipline-Specific Security Analyzers -**Objective:** Build advanced security analyzers for AffineScript and Ephapax disciplines -**Timeline:** Medium-term (3-6 Months) -**Priority:** High +*Objective:* Build advanced security analyzers for AffineScript and +Ephapax disciplines *Timeline:* Medium-term (3-6 Months) *Priority:* +High -## Executive Summary +=== Executive Summary -This plan outlines the development of sophisticated discipline-specific security analyzers that go beyond basic static analysis to provide deep, vision-aligned security validation for AffineScript's affine-first model and Ephapax's dyadic discipline system. +This plan outlines the development of sophisticated discipline-specific +security analyzers that go beyond basic static analysis to provide deep, +vision-aligned security validation for AffineScript’s affine-first model +and Ephapax’s dyadic discipline system. -## Current State Assessment +=== Current State Assessment -### Existing Capabilities -- ✅ Basic static analysis (JET.jl) -- ✅ Code formatting (JuliaFormatter) -- ✅ Package quality (Aqua.jl) -- ✅ CI/CD integration -- ✅ Documentation framework +==== Existing Capabilities -### Discipline-Specific Gaps -- ❌ No deep affine resource analysis -- ❌ No linear discipline enforcement -- ❌ No effect system validation -- ❌ No runtime discipline monitoring -- ❌ No formal verification integration +* ✅ Basic static analysis (JET.jl) +* ✅ Code formatting (JuliaFormatter) +* ✅ Package quality (Aqua.jl) +* ✅ CI/CD integration +* ✅ Documentation framework -## Analyzer Architecture +==== Discipline-Specific Gaps -### High-Level Design +* ❌ No deep affine resource analysis +* ❌ No linear discipline enforcement +* ❌ No effect system validation +* ❌ No runtime discipline monitoring +* ❌ No formal verification integration -``` +=== Analyzer Architecture + +==== High-Level Design + +.... ┌───────────────────────────────────────────────────────┐ │ Discipline Analyzer │ ├───────────────────┬───────────────────┬─────────────────┤ @@ -48,26 +53,28 @@ This plan outlines the development of sophisticated discipline-specific security │ Runtime │ │ Formal │ │ Monitor │ │ Verifier │ └─────────────────┘ └─────────────┘ -``` +.... -### Core Components +==== Core Components -1. **Affine Analyzer** - AffineScript-specific analysis -2. **Linear Analyzer** - Ephapax linear discipline enforcement -3. **Dyadic Analyzer** - Affine/Linear transition and interaction -4. **Effect System Validator** - Algebraic effects security -5. **Runtime Monitor** - Dynamic discipline checking -6. **Formal Verifier** - Integration with proof assistants +[arabic] +. *Affine Analyzer* - AffineScript-specific analysis +. *Linear Analyzer* - Ephapax linear discipline enforcement +. *Dyadic Analyzer* - Affine/Linear transition and interaction +. *Effect System Validator* - Algebraic effects security +. *Runtime Monitor* - Dynamic discipline checking +. *Formal Verifier* - Integration with proof assistants -## Detailed Implementation Plan +=== Detailed Implementation Plan -### 1. Affine Analyzer (High Priority) +==== 1. Affine Analyzer (High Priority) -**Objective:** Deep analysis of affine resource usage patterns +*Objective:* Deep analysis of affine resource usage patterns -#### 1.1 Advanced Resource Tracking +===== 1.1 Advanced Resource Tracking -```julia +[source,julia] +---- module AffineAnalyzer using JET @@ -232,18 +239,17 @@ function generate_affine_report(tracker::AffineTracker) end end # module -``` +---- -**Integration:** -- Extend JET.jl analysis framework -- Add to quality.yml workflow -- Create affine-analysis.yml workflow +*Integration:* - Extend JET.jl analysis framework - Add to quality.yml +workflow - Create affine-analysis.yml workflow -**Timeline:** 6-8 weeks +*Timeline:* 6-8 weeks -#### 1.2 Effect System Deep Analysis +===== 1.2 Effect System Deep Analysis -```julia +[source,julia] +---- module EffectSystemAnalyzer using JET @@ -360,22 +366,21 @@ function check_effect_leaks(context::EffectContext) end end # module -``` +---- -**Integration:** -- Integrate with AffineAnalyzer -- Add to effects-analysis.yml workflow -- Extend training materials +*Integration:* - Integrate with AffineAnalyzer - Add to +effects-analysis.yml workflow - Extend training materials -**Timeline:** 5-7 weeks +*Timeline:* 5-7 weeks -### 2. Linear Analyzer (High Priority) +==== 2. Linear Analyzer (High Priority) -**Objective:** Strict linear discipline enforcement and validation +*Objective:* Strict linear discipline enforcement and validation -#### 2.1 Linear Resource Tracking +===== 2.1 Linear Resource Tracking -```julia +[source,julia] +---- module LinearAnalyzer using JET @@ -550,18 +555,17 @@ function generate_linear_report(tracker::LinearTracker) end end # module -``` +---- -**Integration:** -- Extend JET.jl with linear analysis -- Add to quality.yml workflow -- Create linear-analysis.yml workflow +*Integration:* - Extend JET.jl with linear analysis - Add to quality.yml +workflow - Create linear-analysis.yml workflow -**Timeline:** 6-8 weeks +*Timeline:* 6-8 weeks -#### 2.2 Linear Discipline Enforcement +===== 2.2 Linear Discipline Enforcement -```julia +[source,julia] +---- module LinearEnforcer using .LinearAnalyzer @@ -693,22 +697,22 @@ function generate_enforcement_report(tracker::LinearTracker, violations::Vector{ end end # module -``` +---- -**Integration:** -- Add strict linear enforcement mode -- Create linear-enforcement.yml workflow -- Document linear discipline best practices +*Integration:* - Add strict linear enforcement mode - Create +linear-enforcement.yml workflow - Document linear discipline best +practices -**Timeline:** 5-7 weeks +*Timeline:* 5-7 weeks -### 3. Dyadic Analyzer (High Priority) +==== 3. Dyadic Analyzer (High Priority) -**Objective:** Analyze affine/linear interactions and transitions +*Objective:* Analyze affine/linear interactions and transitions -#### 3.1 Discipline Boundary Analysis +===== 3.1 Discipline Boundary Analysis -```julia +[source,julia] +---- module DyadicAnalyzer using .AffineAnalyzer @@ -933,18 +937,17 @@ function generate_dyadic_report(tracker::DyadicTracker) end end # module -``` +---- -**Integration:** -- Combine affine and linear analyzers -- Add to dyadic-analysis.yml workflow -- Create transition-assistant.yml workflow +*Integration:* - Combine affine and linear analyzers - Add to +dyadic-analysis.yml workflow - Create transition-assistant.yml workflow -**Timeline:** 8-10 weeks +*Timeline:* 8-10 weeks -#### 3.2 Transition Assistant +===== 3.2 Transition Assistant -```julia +[source,julia] +---- module TransitionAssistant using .DyadicAnalyzer @@ -1108,22 +1111,22 @@ function interactive_migration_assistant() end end # module -``` +---- -**Integration:** -- Add interactive migration tool -- Create migration-assistant.yml workflow -- Extend training with migration patterns +*Integration:* - Add interactive migration tool - Create +migration-assistant.yml workflow - Extend training with migration +patterns -**Timeline:** 6-8 weeks +*Timeline:* 6-8 weeks -### 4. Runtime Monitor (Medium Priority) +==== 4. Runtime Monitor (Medium Priority) -**Objective:** Dynamic discipline checking and runtime validation +*Objective:* Dynamic discipline checking and runtime validation -#### 4.1 Discipline Runtime Instrumentation +===== 4.1 Discipline Runtime Instrumentation -```julia +[source,julia] +---- module RuntimeMonitor using .AffineAnalyzer @@ -1326,18 +1329,17 @@ function generate_runtime_report(monitor::DisciplineRuntime) end end # module -``` +---- -**Integration:** -- Add runtime monitoring to production builds -- Create runtime-monitor.yml workflow -- Document runtime discipline patterns +*Integration:* - Add runtime monitoring to production builds - Create +runtime-monitor.yml workflow - Document runtime discipline patterns -**Timeline:** 8-12 weeks +*Timeline:* 8-12 weeks -#### 4.2 Discipline Violation Dashboard +===== 4.2 Discipline Violation Dashboard -```julia +[source,julia] +---- module ViolationDashboard using .RuntimeMonitor @@ -1573,22 +1575,22 @@ function start_dashboard_server(dashboard::ViolationDashboard, port::Int=8080) end end # module -``` +---- -**Integration:** -- Add dashboard to production monitoring -- Create dashboard-server.yml workflow -- Document runtime monitoring best practices +*Integration:* - Add dashboard to production monitoring - Create +dashboard-server.yml workflow - Document runtime monitoring best +practices -**Timeline:** 10-12 weeks +*Timeline:* 10-12 weeks -### 5. Formal Verifier (Long-term) +==== 5. Formal Verifier (Long-term) -**Objective:** Integration with proof assistants for formal verification +*Objective:* Integration with proof assistants for formal verification -#### 5.1 Proof Assistant Integration +===== 5.1 Proof Assistant Integration -```julia +[source,julia] +---- module FormalVerifier using .AffineAnalyzer @@ -1902,148 +1904,174 @@ function generate_verification_report(context::VerificationContext) end end # module -``` - -**Integration:** -- Add formal verification to CI/CD -- Create formal-verification.yml workflow -- Document formal methods integration - -**Timeline:** 12-16 weeks (long-term) - -## Implementation Roadmap - -### Phase 1: Core Analyzers (Weeks 1-8) -- [ ] Affine Analyzer foundation -- [ ] Linear Analyzer foundation -- [ ] Basic effect system analysis -- [ ] Simple discipline boundary tracking -- [ ] Integration with existing tools -- [ ] Basic CI/CD workflow updates - -### Phase 2: Advanced Features (Weeks 9-16) -- [ ] Complete effect system validation -- [ ] Full linear discipline enforcement -- [ ] Dyadic transition analysis -- [ ] Transition assistant tools -- [ ] Enhanced documentation -- [ ] Training material updates - -### Phase 3: Runtime & Formal (Weeks 17-24) -- [ ] Runtime monitor foundation -- [ ] Basic violation tracking -- [ ] Formal verifier setup -- [ ] Proof assistant integration -- [ ] Dashboard prototype -- [ ] Advanced workflows - -### Phase 4: Optimization & Deployment (Weeks 25-32) -- [ ] Performance optimization -- [ ] Error handling improvement -- [ ] Production deployment -- [ ] User testing -- [ ] Final documentation -- [ ] Community release - -## Resource Requirements - -### Development Team -- **2 Julia Developers** (primary implementation) -- **1 Formal Methods Expert** (verification integration) -- **1 Security Specialist** (discipline-specific patterns) -- **1 Documentation Writer** (advanced training) -- **1 QA Engineer** (comprehensive testing) - -### Tools & Technologies -- Julia 1.10+ -- JET.jl, JuliaFormatter, Aqua.jl -- Lean Theorem Prover or Coq -- GitHub Actions -- WASM tooling -- Plots.jl (for visualization) -- HTTP.jl, WebSockets.jl - -### Budget Estimate -- **Development:** 600-800 hours -- **Research:** 200-300 hours -- **Testing:** 300-400 hours -- **Documentation:** 200-300 hours -- **Total:** 1300-1800 hours (~8-12 months FTE) - -## Success Metrics - -### Quantitative Goals -- **Affine Analysis:** 95%+ resource tracking accuracy -- **Linear Enforcement:** 90%+ consumption verification -- **Effect Validation:** 85%+ effect handler coverage -- **Runtime Monitoring:** <5% false positives -- **Formal Verification:** 70%+ proof success rate - -### Qualitative Goals -- **Developer Experience:** Seamless integration with existing workflows -- **Vision Alignment:** Direct support for AffineScript/Ephapax disciplines -- **Documentation Quality:** Comprehensive, example-rich guides -- **Performance Impact:** <10% build time increase -- **Adoption Rate:** 80%+ of target projects within 12 months - -## Risk Assessment - -### Technical Risks -1. **Complexity** - Mitigation: Modular design, incremental development -2. **Performance** - Mitigation: Optimization phase, profiling -3. **Integration** - Mitigation: Comprehensive testing, CI/CD validation -4. **False Positives** - Mitigation: Tunable sensitivity, developer feedback -5. **Formal Methods** - Mitigation: Start with simple theorems, gradual complexity - -### Schedule Risks -1. **Research Delays** - Mitigation: Parallel development paths -2. **Scope Creep** - Mitigation: Clear phase boundaries, regular reviews -3. **Dependency Issues** - Mitigation: Version pinning, compatibility testing -4. **Team Availability** - Mitigation: Realistic scheduling, buffer time - -### Adoption Risks -1. **Learning Curve** - Mitigation: Comprehensive training, gradual rollout -2. **Workflow Changes** - Mitigation: Backward compatibility, migration tools -3. **Performance Concerns** - Mitigation: Benchmarking, optimization -4. **False Positives** - Mitigation: Developer feedback loop, continuous improvement - -## Monitoring and Evaluation - -### Progress Tracking -- Bi-weekly technical reviews -- Monthly stakeholder updates -- Quarterly vision alignment workshops -- Continuous integration testing - -### Quality Assurance -- Unit tests for each analyzer component -- Integration tests for workflows -- Performance benchmarks -- User acceptance testing -- Security audit validation - -### Feedback Loops -- Developer preview releases -- Community feedback sessions -- Vision alignment workshops -- Continuous improvement cycle -- Production monitoring - -## Conclusion - -This plan outlines a comprehensive approach to building discipline-specific security analyzers that directly support the AffineScript and Ephapax visions. By developing advanced affine analysis, linear enforcement, dyadic transition tools, runtime monitoring, and formal verification integration, we will create a world-class security infrastructure for modern programming languages. - -The implementation is structured in four phases over 32 weeks, with clear milestones and success metrics. The analyzers will provide deep, vision-aligned security validation while maintaining compatibility with existing development workflows. - -**Next Steps:** -1. Begin Phase 1 implementation -2. Set up development environment -3. Create core analyzer modules -4. Implement basic affine/linear tracking -5. Schedule bi-weekly progress reviews -6. Establish vision alignment review process - -**Maintainers:** @hyperpolymath/core-team -**Implementation Lead:** [To be assigned] -**Target Completion:** 2024-12-14 -**Review Dates:** 2024-08-14 (Phase 1), 2024-10-14 (Phase 2), 2024-12-14 (Final) \ No newline at end of file +---- + +*Integration:* - Add formal verification to CI/CD - Create +formal-verification.yml workflow - Document formal methods integration + +*Timeline:* 12-16 weeks (long-term) + +=== Implementation Roadmap + +==== Phase 1: Core Analyzers (Weeks 1-8) + +* [ ] Affine Analyzer foundation +* [ ] Linear Analyzer foundation +* [ ] Basic effect system analysis +* [ ] Simple discipline boundary tracking +* [ ] Integration with existing tools +* [ ] Basic CI/CD workflow updates + +==== Phase 2: Advanced Features (Weeks 9-16) + +* [ ] Complete effect system validation +* [ ] Full linear discipline enforcement +* [ ] Dyadic transition analysis +* [ ] Transition assistant tools +* [ ] Enhanced documentation +* [ ] Training material updates + +==== Phase 3: Runtime & Formal (Weeks 17-24) + +* [ ] Runtime monitor foundation +* [ ] Basic violation tracking +* [ ] Formal verifier setup +* [ ] Proof assistant integration +* [ ] Dashboard prototype +* [ ] Advanced workflows + +==== Phase 4: Optimization & Deployment (Weeks 25-32) + +* [ ] Performance optimization +* [ ] Error handling improvement +* [ ] Production deployment +* [ ] User testing +* [ ] Final documentation +* [ ] Community release + +=== Resource Requirements + +==== Development Team + +* *2 Julia Developers* (primary implementation) +* *1 Formal Methods Expert* (verification integration) +* *1 Security Specialist* (discipline-specific patterns) +* *1 Documentation Writer* (advanced training) +* *1 QA Engineer* (comprehensive testing) + +==== Tools & Technologies + +* Julia 1.10+ +* JET.jl, JuliaFormatter, Aqua.jl +* Lean Theorem Prover or Coq +* GitHub Actions +* WASM tooling +* Plots.jl (for visualization) +* HTTP.jl, WebSockets.jl + +==== Budget Estimate + +* *Development:* 600-800 hours +* *Research:* 200-300 hours +* *Testing:* 300-400 hours +* *Documentation:* 200-300 hours +* *Total:* 1300-1800 hours (~8-12 months FTE) + +=== Success Metrics + +==== Quantitative Goals + +* *Affine Analysis:* 95%+ resource tracking accuracy +* *Linear Enforcement:* 90%+ consumption verification +* *Effect Validation:* 85%+ effect handler coverage +* *Runtime Monitoring:* <5% false positives +* *Formal Verification:* 70%+ proof success rate + +==== Qualitative Goals + +* *Developer Experience:* Seamless integration with existing workflows +* *Vision Alignment:* Direct support for AffineScript/Ephapax +disciplines +* *Documentation Quality:* Comprehensive, example-rich guides +* *Performance Impact:* <10% build time increase +* *Adoption Rate:* 80%+ of target projects within 12 months + +=== Risk Assessment + +==== Technical Risks + +[arabic] +. *Complexity* - Mitigation: Modular design, incremental development +. *Performance* - Mitigation: Optimization phase, profiling +. *Integration* - Mitigation: Comprehensive testing, CI/CD validation +. *False Positives* - Mitigation: Tunable sensitivity, developer +feedback +. *Formal Methods* - Mitigation: Start with simple theorems, gradual +complexity + +==== Schedule Risks + +[arabic] +. *Research Delays* - Mitigation: Parallel development paths +. *Scope Creep* - Mitigation: Clear phase boundaries, regular reviews +. *Dependency Issues* - Mitigation: Version pinning, compatibility +testing +. *Team Availability* - Mitigation: Realistic scheduling, buffer time + +==== Adoption Risks + +[arabic] +. *Learning Curve* - Mitigation: Comprehensive training, gradual rollout +. *Workflow Changes* - Mitigation: Backward compatibility, migration +tools +. *Performance Concerns* - Mitigation: Benchmarking, optimization +. *False Positives* - Mitigation: Developer feedback loop, continuous +improvement + +=== Monitoring and Evaluation + +==== Progress Tracking + +* Bi-weekly technical reviews +* Monthly stakeholder updates +* Quarterly vision alignment workshops +* Continuous integration testing + +==== Quality Assurance + +* Unit tests for each analyzer component +* Integration tests for workflows +* Performance benchmarks +* User acceptance testing +* Security audit validation + +==== Feedback Loops + +* Developer preview releases +* Community feedback sessions +* Vision alignment workshops +* Continuous improvement cycle +* Production monitoring + +=== Conclusion + +This plan outlines a comprehensive approach to building +discipline-specific security analyzers that directly support the +AffineScript and Ephapax visions. By developing advanced affine +analysis, linear enforcement, dyadic transition tools, runtime +monitoring, and formal verification integration, we will create a +world-class security infrastructure for modern programming languages. + +The implementation is structured in four phases over 32 weeks, with +clear milestones and success metrics. The analyzers will provide deep, +vision-aligned security validation while maintaining compatibility with +existing development workflows. + +*Next Steps:* 1. Begin Phase 1 implementation 2. Set up development +environment 3. Create core analyzer modules 4. Implement basic +affine/linear tracking 5. Schedule bi-weekly progress reviews 6. +Establish vision alignment review process + +*Maintainers:* @hyperpolymath/core-team *Implementation Lead:* [To be +assigned] *Target Completion:* 2024-12-14 *Review Dates:* 2024-08-14 +(Phase 1), 2024-10-14 (Phase 2), 2024-12-14 (Final) diff --git a/FIXING-DESKTOP-ICONS.adoc b/FIXING-DESKTOP-ICONS.adoc new file mode 100644 index 00000000..1f2c0ce9 --- /dev/null +++ b/FIXING-DESKTOP-ICONS.adoc @@ -0,0 +1,148 @@ +== Fixing PanLL Desktop Icon Issues + +____ +*Updated 2026-04-10.* The PanLL launcher is now scaffolder-managed and +lives *in-repo* at `+/var/mnt/eclipse/repos/panll/panll-launcher.sh+`. +It is regenerated by +https://github.com/hyperpolymath/launch-scaffolder[`+launch-scaffolder+`] +from `+panll.launcher.a2ml+`. The pre-2026-04-10 hand-written copy under +`+~/.desktop-tools/panll-launcher.sh+` was archived to +`+~/.desktop-tools/.archive-2026-04-10/+` and should not be used. This +document has been updated to reference the new path; the advice below +still applies to the scaffolder-generated script. +____ + +=== Problem + +The PanLL desktop icon shows an error: "`Unable to make the service +PanLL executable, aborting execution. Existing file +/home/hyper/Desktop/panll.desktop is not writable.`" + +=== Root Cause + +The desktop file is *read-only (444)* for security, but something is +trying to modify it after creation. + +=== Solution + +==== Option 1: Don’t use the install script + +Simply launch PanLL directly from the existing desktop icon. The +launcher is already configured correctly. + +==== Option 2: Modify the install script + +If you need to reinstall, modify `+scripts/install-desktop.sh+` to not +change desktop file permissions: + +[source,bash] +---- +# Remove or comment out this line: +# chmod +x "$APPS_DIR/${APP_NAME}.desktop" +---- + +==== Option 3: Temporarily make writable + +If you must modify the desktop file: + +[source,bash] +---- +# Make writable +sudo chmod 644 /home/hyper/Desktop/panll.desktop + +# Make your changes + +# Restore protection +sudo chmod 444 /home/hyper/Desktop/panll.desktop +---- + +=== Current Status + +✅ *Desktop file is properly configured* - Exec: +`+/var/mnt/eclipse/repos/panll/panll-launcher.sh serve+` - Terminal: +false - Permissions: 444 (read-only, secure) + +✅ *Launcher is fixed* - Uses `+nohup+` for background processes - Waits +for server to be ready - Keeps running with `+tail -f /dev/null+` - +Opens browser automatically + +=== How to Launch + +[arabic] +. *From desktop icon*: Click the PanLL icon in your desktop environment +. *From terminal*: +`+/var/mnt/eclipse/repos/panll/panll-launcher.sh serve+` +. *Stop*: `+/var/mnt/eclipse/repos/panll/panll-launcher.sh stop+` + +=== Verification + +[source,bash] +---- +# Check if server is running +curl -v http://localhost:3000 + +# Check logs + tail -50 /tmp/panll-server.log + +# Check process +ps aux | grep panll +---- + +=== Troubleshooting + +If it still doesn’t work: + +[arabic] +. *Check Gossamer*: `+command -v gossamer && gossamer --version+` +. *Check Deno*: `+command -v deno && deno --version+` +. *Check actual port*: `+ss -tlnp | grep deno+` or `+lsof -i :8000+` +. *Verify launcher port matches*: +`+grep "URL=" /var/mnt/eclipse/repos/panll/panll-launcher.sh+` +. *Update launcher if needed*: Change URL in launcher to match actual +server port +. *Run diagnostics*: `+panll-dustfile.sh --diagnose+` +. *Try repair*: `+panll-dustfile.sh --repair+` + +==== Common Port Issues + +The launcher and server ports must match: + +[source,bash] +---- +# Check what port the server is actually using +ss -tlnp | grep deno + +# Check what port the launcher expects +grep "URL=" /var/mnt/eclipse/repos/panll/panll-launcher.sh + +# If they don't match, update the launcher: +sed -i 's|URL="http://localhost:3000"|URL="http://localhost:8000"|' /var/mnt/eclipse/repos/panll/panll-launcher.sh +---- + +Default ports: - PanLL: 8000 (deno dev server) - IDApTIK: 8080 - Game +Server Admin: VeriSimDB on 8090 + +=== Security Note + +Desktop files use *555 permissions* (read+execute, no write) for +security. This prevents: - Accidental modification - Malware tampering - +Unauthorized changes - Code injection attacks + +While still allowing: - Execution by desktop environment - Reading by +users - Legitimate updates (temporarily change to 755) + +==== Permission Reference: + +* `+444+` = read-only (too restrictive, can’t execute) +* `+555+` = read+execute (recommended for desktop files) +* `+644+` = read+write for owner (use temporarily for updates) +* `+755+` = read+execute for all, write for owner (standard for scripts) + +To modify temporarily: + +[source,bash] +---- +sudo chmod 755 /home/hyper/Desktop/panll.desktop +# Make your changes +sudo chmod 555 /home/hyper/Desktop/panll.desktop +---- diff --git a/FIXING-DESKTOP-ICONS.md b/FIXING-DESKTOP-ICONS.md deleted file mode 100644 index 2491728f..00000000 --- a/FIXING-DESKTOP-ICONS.md +++ /dev/null @@ -1,133 +0,0 @@ -# Fixing PanLL Desktop Icon Issues - -> **Updated 2026-04-10.** The PanLL launcher is now scaffolder-managed -> and lives **in-repo** at `/var/mnt/eclipse/repos/panll/panll-launcher.sh`. -> It is regenerated by -> [`launch-scaffolder`](https://github.com/hyperpolymath/launch-scaffolder) -> from `panll.launcher.a2ml`. The pre-2026-04-10 hand-written copy -> under `~/.desktop-tools/panll-launcher.sh` was archived to -> `~/.desktop-tools/.archive-2026-04-10/` and should not be used. -> This document has been updated to reference the new path; the -> advice below still applies to the scaffolder-generated script. - -## Problem -The PanLL desktop icon shows an error: "Unable to make the service PanLL executable, aborting execution. Existing file /home/hyper/Desktop/panll.desktop is not writable." - -## Root Cause -The desktop file is **read-only (444)** for security, but something is trying to modify it after creation. - -## Solution - -### Option 1: Don't use the install script -Simply launch PanLL directly from the existing desktop icon. The launcher is already configured correctly. - -### Option 2: Modify the install script -If you need to reinstall, modify `scripts/install-desktop.sh` to not change desktop file permissions: - -```bash -# Remove or comment out this line: -# chmod +x "$APPS_DIR/${APP_NAME}.desktop" -``` - -### Option 3: Temporarily make writable -If you must modify the desktop file: - -```bash -# Make writable -sudo chmod 644 /home/hyper/Desktop/panll.desktop - -# Make your changes - -# Restore protection -sudo chmod 444 /home/hyper/Desktop/panll.desktop -``` - -## Current Status - -✅ **Desktop file is properly configured** -- Exec: `/var/mnt/eclipse/repos/panll/panll-launcher.sh serve` -- Terminal: false -- Permissions: 444 (read-only, secure) - -✅ **Launcher is fixed** -- Uses `nohup` for background processes -- Waits for server to be ready -- Keeps running with `tail -f /dev/null` -- Opens browser automatically - -## How to Launch - -1. **From desktop icon**: Click the PanLL icon in your desktop environment -2. **From terminal**: `/var/mnt/eclipse/repos/panll/panll-launcher.sh serve` -3. **Stop**: `/var/mnt/eclipse/repos/panll/panll-launcher.sh stop` - -## Verification - -```bash -# Check if server is running -curl -v http://localhost:3000 - -# Check logs - tail -50 /tmp/panll-server.log - -# Check process -ps aux | grep panll -``` - -## Troubleshooting - -If it still doesn't work: - -1. **Check Gossamer**: `command -v gossamer && gossamer --version` -2. **Check Deno**: `command -v deno && deno --version` -3. **Check actual port**: `ss -tlnp | grep deno` or `lsof -i :8000` -4. **Verify launcher port matches**: `grep "URL=" /var/mnt/eclipse/repos/panll/panll-launcher.sh` -5. **Update launcher if needed**: Change URL in launcher to match actual server port -6. **Run diagnostics**: `panll-dustfile.sh --diagnose` -7. **Try repair**: `panll-dustfile.sh --repair` - -### Common Port Issues - -The launcher and server ports must match: - -```bash -# Check what port the server is actually using -ss -tlnp | grep deno - -# Check what port the launcher expects -grep "URL=" /var/mnt/eclipse/repos/panll/panll-launcher.sh - -# If they don't match, update the launcher: -sed -i 's|URL="http://localhost:3000"|URL="http://localhost:8000"|' /var/mnt/eclipse/repos/panll/panll-launcher.sh -``` - -Default ports: -- PanLL: 8000 (deno dev server) -- IDApTIK: 8080 -- Game Server Admin: VeriSimDB on 8090 - -## Security Note - -Desktop files use **555 permissions** (read+execute, no write) for security. This prevents: -- Accidental modification -- Malware tampering -- Unauthorized changes -- Code injection attacks - -While still allowing: -- Execution by desktop environment -- Reading by users -- Legitimate updates (temporarily change to 755) - -### Permission Reference: -- `444` = read-only (too restrictive, can't execute) -- `555` = read+execute (recommended for desktop files) -- `644` = read+write for owner (use temporarily for updates) -- `755` = read+execute for all, write for owner (standard for scripts) - -To modify temporarily: -```bash -sudo chmod 755 /home/hyper/Desktop/panll.desktop -# Make your changes -sudo chmod 555 /home/hyper/Desktop/panll.desktop -``` diff --git a/GEMINI.adoc b/GEMINI.adoc new file mode 100644 index 00000000..b4125b96 --- /dev/null +++ b/GEMINI.adoc @@ -0,0 +1,305 @@ +== PanLL — AI Coordination Rules + +____ +*Auto-generated from `+coordination.k9+`* — do not edit directly. +Re-generate with: +`+deno run --allow-read --allow-write generate.js coordination.k9+` +Source of truth: `+coordination.k9+` in repository root. +____ + +=== Project + +Neurosymbolic IDE built on the Binary Star model — human (symbolic, +Panel-L) and machine (neural, Panel-N) orbiting a shared world state +(Panel-W). 106 panels, custom TEA runtime, Gossamer desktop backend. + +*Languages:* ReScript, Rust, Elixir, JavaScript *License:* MPL-2.0 +*Build system:* just *Runtime:* deno + +=== Build Commands + +[cols=",",options="header",] +|=== +|Command |Description +|`+just build+` |Full build (ReScript + CSS + bundle) +|`+just res+` |ReScript compile only +|`+just bundle+` |esbuild bundle +|`+just css+` |Build CSS +|`+just dev+` |Start dev server on port 8000 +|`+just test+` |Run test suite (979 tests, 41 suites) +|`+just coverage+` |Run tests with coverage +|`+just lint+` |Lint ReScript source +|`+just doctor+` |Run project health checks +|=== + +=== INVARIANTS — Do Not Violate + +These rules are non-negotiable. Violating them will break the project or +contradict deliberate architectural decisions. + +==== [CRITICAL] custom-tea-runtime + +*Rule:* The custom TEA runtime in src/tea/ (18 modules) must NEVER be +replaced with rescript-tea or any other library + +*Why:* rescript-tea was deliberately evaluated and rejected. The custom +TEA runtime handles PanLL-specific needs: Anti-Crash circuit breaking, +Vexometer cognitive load adaptation, OrbitalSync multi-panel state +coherence, and panel lifecycle management. It is not legacy — it is the +architecture. + +==== [CRITICAL] no-typescript + +*Rule:* Do not introduce TypeScript files — ReScript is the frontend +language + +*Why:* ReScript provides better type safety with less overhead. This is +a deliberate, ecosystem-wide decision. + +==== [CRITICAL] no-tauri + +*Rule:* Do not introduce Tauri references or dependencies — Gossamer is +the desktop backend + +*Why:* PanLL was migrated FROM Tauri 2.0 TO Gossamer. This migration is +complete and intentional. + +==== [CRITICAL] tea-pattern-only + +*Rule:* All state management uses TEA (Model -> Msg -> Update -> View) — +no MVC, Redux, hooks, or other patterns + +*Why:* TEA is foundational to PanLL’s architecture. Model.res holds all +state, Msg.res defines all messages, Update.res is the state transition +kernel. + +==== [CRITICAL] all-state-in-model + +*Rule:* ALL application state lives in Model.model — no global mutable +state, no module-level state, no window.* state + +*Why:* TEA requires single state tree. Anti-Crash and OrbitalSync depend +on this invariant for correctness. + +==== [CRITICAL] no-npm-bun + +*Rule:* No npm, Bun, pnpm, or yarn — Deno is the orchestrator + +*Why:* Deno-only build (post panll#65). ReScript and Tailwind run via +`+npm:+` specifiers in `+deno.json+` — there is no `+package.json+` and +no npm CLI is invoked. Do not reintroduce npm/bun/yarn/pnpm tooling. + +==== [CRITICAL] anticrash-validates-all + +*Rule:* Anti-Crash circuit breaker validates ALL neural tokens before +symbolic execution — never bypass this + +*Why:* Safety-critical: prevents untrusted neural output from corrupting +symbolic state. The validation path exists for a reason. + +==== [HIGH] panels-not-panes + +*Rule:* UI elements are called '`panels`', NEVER '`panes`', '`tabs`', or +'`windows`' + +*Why:* PanLL naming convention — '`panels`' is the correct term +everywhere in code, docs, and communication + +==== [CRITICAL] no-bulk-panel-deletion + +*Rule:* Do not delete more than 2 panel files in a single operation +without explicit user approval + +*Why:* 106 panels have complex interdependencies. Bulk deletion can +cascade and break OrbitalSync. + +==== [HIGH] gossamer-bridge-pattern + +*Rule:* Gossamer commands in src/commands/ are invoke wrappers only — do +not put business logic there + +*Why:* Business logic belongs in Update.res. Commands are thin bridges +to the Gossamer backend. + +==== [CRITICAL] binary-star-model + +*Rule:* The Binary Star architecture (Panel-L symbolic + Panel-N neural ++ Panel-W world) is deliberate — do not flatten into a single panel type + +*Why:* The three panel types serve fundamentally different roles. This +is the core design of PanLL. + +==== [CRITICAL] rescript-core-team + +*Rule:* The project owner is on the ReScript core team — do not suggest +migrating away from ReScript + +*Why:* ReScript is not a temporary choice. The owner contributes to +ReScript itself. + +=== Protected Files and Directories + +Do NOT delete, reorganise, or replace these without explicit user +approval: + +[width="100%",cols="43%,57%",options="header",] +|=== +|Path |Reason +|`+src/tea/+` |Custom TEA runtime — 18 modules. NEVER replace with +rescript-tea. + +|`+src/Model.res+` |Single state tree — all application state lives here + +|`+src/Msg.res+` |Message type definitions — the TEA message catalogue + +|`+src/Update.res+` |State transition kernel — ~7500 lines, the heart of +PanLL + +|`+src/View.res+` |Root view renderer + +|`+src/App.res+` |Application entry point + +|`+src/core/+` |Core engines — AntiCrash, OrbitalSync, Contractiles, +TypeLLEngine, VabEngine + +|`+src/components/+` |106 panel views — do not bulk-delete + +|`+src/commands/+` |Gossamer bridge commands — thin wrappers only + +|`+src/modules/+` |Module registry + TypeLLService — cross-panel type +intelligence + +|`+src-gossamer/+` |Rust backend (WebKitGTK) — Gossamer desktop +integration + +|`+beam/+` |Elixir/BEAM API layer + +|`+tests/+` |979 tests, 41 suites — never delete tests + +|`+.machine_readable/+` |Canonical location for A2ML state files — MUST +stay here + +|`+coordination.k9+` |This file — source of truth for AI coordination +|=== + +=== Architecture Decisions (Deliberate) + +These choices may look unusual but are intentional: + +==== gossamer-not-tauri + +*Decision:* Gossamer (Zig + WebKitGTK) is the desktop backend — +migration from Tauri 2.0 is complete + +*Why:* Gossamer is the hyperpolymath desktop runtime. Tauri was used +previously but replaced. + +*Rejected alternatives:* Tauri 2.0, Electron, native GTK + +==== custom-tea-not-rescript-tea + +*Decision:* Custom TEA runtime (src/tea/, 18 modules) instead of the +rescript-tea library + +*Why:* PanLL needs Anti-Crash integration, OrbitalSync, Vexometer hooks, +and panel lifecycle — none available in rescript-tea + +*Rejected alternatives:* rescript-tea, Redux, MobX, React hooks pattern + +==== deno-only-with-npm-specifiers + +*Decision:* Deno orchestrates everything; ReScript and Tailwind run via +`+npm:+` specifiers in `+deno.json+` + +*Why:* Post panll#65: `+package.json+` + `+package-lock.json+` deleted; +ReScript compiles via +`+deno run -A --allow-scripts=npm:rescript npm:rescript@^12.0.0 build+`, +Tailwind via `+deno run -A npm:tailwindcss+`. No npm CLI invocation. Do +not extend npm’s role. + +==== binary-star + +*Decision:* Three panel types: Panel-L (symbolic/human), Panel-N +(neural/machine), Panel-W (world/shared) + +*Why:* Neurosymbolic architecture requires clear separation of human +reasoning, machine inference, and shared world state + +==== vexometer-cognitive-load + +*Decision:* Vexometer monitors operator stress and adapts UI detail +density + +*Why:* HTI (Human-Tool Interaction) principle — the IDE adapts to the +human, not vice versa + +==== anticrash-circuit-breaker + +*Decision:* Anti-Crash validates all neural tokens before they enter the +symbolic pipeline + +*Why:* Safety boundary between neural and symbolic systems — prevents +hallucinated code from corrupting state + +=== Do NOT Create + +These files, patterns, or systems must NOT be introduced: + +* ****/*.ts** — TypeScript is banned — use ReScript +* *Dockerfile* — Use Containerfile (Podman, not Docker) +* ****/*.py** — Python is banned — use ReScript, Rust, or Elixir +* *A replacement TEA runtime or state management library* — src/tea/ is +the TEA runtime — it is custom, deliberate, and must not be replaced +* *REST API endpoints parallel to existing Groove protocol endpoints* — +Groove is the inter-service communication protocol — do not create REST +alternatives +* *A new panel type beyond Panel-L, Panel-N, Panel-W* — Binary Star +model has exactly three types — adding more would break OrbitalSync +* *Direct Tauri imports or tauri.conf.json* — Tauri migration to +Gossamer is complete — do not reintroduce + +=== Terminology + +Use the correct terms for this project: + +* Say *"`panels`"*, NOT "`panes`", "`tabs`", "`windows`" +** PanLL UI elements are always called panels — this is enforced +everywhere +* Say *"`Binary Star`"*, NOT "`dual-pane`", "`split-view`", +"`two-panel`" +** The architectural model is Binary Star (Panel-L + Panel-N orbiting +Panel-W) +* Say *"`Anti-Crash`"*, NOT "`validator`", "`sanitizer`", "`filter`" +** The neural token validation system is called Anti-Crash +* Say *"`Vexometer`"*, NOT "`stress meter`", "`load indicator`", +"`fatigue tracker`" +** The cognitive load monitoring system is called Vexometer +* Say *"`OrbitalSync`"*, NOT "`state sync`", "`panel sync`", "`sync +engine`" +** The multi-panel state coherence system is called OrbitalSync + +=== Port Assignments + +[cols=",",options="header",] +|=== +|Service |Port +|dev-server |8000 +|echidna |9000 +|verisim |8080 +|boj-server |7700 +|typell |7800 +|=== + +=== Ecosystem Context + +*Depends on:* - *gossamer* — Desktop backend runtime (Zig + WebKitGTK) - +*verisim* — Persistent storage layer - *typell* — Type intelligence +engine — cross-panel type checking - *boj-server* — MCP server — all +external tool integration + +*Consumed by:* - *idaptik* — Uses PanLL as level editor for game content + +*Related projects:* - *echidna* — Proof engine — formal verification +integration - *hypatia* — Neurosymbolic CI/CD scanning - *panic-attack* +— Security scanning tool - *gitbot-fleet* — Bot orchestration (rhodibot, +echidnabot, etc.) - *proven* — Formally verified alternatives library diff --git a/GEMINI.md b/GEMINI.md deleted file mode 100644 index 8e49ca27..00000000 --- a/GEMINI.md +++ /dev/null @@ -1,230 +0,0 @@ - - - - -# PanLL — AI Coordination Rules - -> **Auto-generated from `coordination.k9`** — do not edit directly. -> Re-generate with: `deno run --allow-read --allow-write generate.js coordination.k9` -> Source of truth: `coordination.k9` in repository root. - -## Project - -Neurosymbolic IDE built on the Binary Star model — human (symbolic, Panel-L) and machine (neural, Panel-N) orbiting a shared world state (Panel-W). 106 panels, custom TEA runtime, Gossamer desktop backend. - -**Languages:** ReScript, Rust, Elixir, JavaScript -**License:** MPL-2.0 -**Build system:** just -**Runtime:** deno - -## Build Commands - -| Command | Description | -|---------|-------------| -| `just build` | Full build (ReScript + CSS + bundle) | -| `just res` | ReScript compile only | -| `just bundle` | esbuild bundle | -| `just css` | Build CSS | -| `just dev` | Start dev server on port 8000 | -| `just test` | Run test suite (979 tests, 41 suites) | -| `just coverage` | Run tests with coverage | -| `just lint` | Lint ReScript source | -| `just doctor` | Run project health checks | - -## INVARIANTS — Do Not Violate - -These rules are non-negotiable. Violating them will break the project -or contradict deliberate architectural decisions. - -### [CRITICAL] custom-tea-runtime - -**Rule:** The custom TEA runtime in src/tea/ (18 modules) must NEVER be replaced with rescript-tea or any other library - -**Why:** rescript-tea was deliberately evaluated and rejected. The custom TEA runtime handles PanLL-specific needs: Anti-Crash circuit breaking, Vexometer cognitive load adaptation, OrbitalSync multi-panel state coherence, and panel lifecycle management. It is not legacy — it is the architecture. - -### [CRITICAL] no-typescript - -**Rule:** Do not introduce TypeScript files — ReScript is the frontend language - -**Why:** ReScript provides better type safety with less overhead. This is a deliberate, ecosystem-wide decision. - -### [CRITICAL] no-tauri - -**Rule:** Do not introduce Tauri references or dependencies — Gossamer is the desktop backend - -**Why:** PanLL was migrated FROM Tauri 2.0 TO Gossamer. This migration is complete and intentional. - -### [CRITICAL] tea-pattern-only - -**Rule:** All state management uses TEA (Model -> Msg -> Update -> View) — no MVC, Redux, hooks, or other patterns - -**Why:** TEA is foundational to PanLL's architecture. Model.res holds all state, Msg.res defines all messages, Update.res is the state transition kernel. - -### [CRITICAL] all-state-in-model - -**Rule:** ALL application state lives in Model.model — no global mutable state, no module-level state, no window.* state - -**Why:** TEA requires single state tree. Anti-Crash and OrbitalSync depend on this invariant for correctness. - -### [CRITICAL] no-npm-bun - -**Rule:** No npm, Bun, pnpm, or yarn — Deno is the orchestrator - -**Why:** Deno-only build (post panll#65). ReScript and Tailwind run via `npm:` specifiers in `deno.json` — there is no `package.json` and no npm CLI is invoked. Do not reintroduce npm/bun/yarn/pnpm tooling. - -### [CRITICAL] anticrash-validates-all - -**Rule:** Anti-Crash circuit breaker validates ALL neural tokens before symbolic execution — never bypass this - -**Why:** Safety-critical: prevents untrusted neural output from corrupting symbolic state. The validation path exists for a reason. - -### [HIGH] panels-not-panes - -**Rule:** UI elements are called 'panels', NEVER 'panes', 'tabs', or 'windows' - -**Why:** PanLL naming convention — 'panels' is the correct term everywhere in code, docs, and communication - -### [CRITICAL] no-bulk-panel-deletion - -**Rule:** Do not delete more than 2 panel files in a single operation without explicit user approval - -**Why:** 106 panels have complex interdependencies. Bulk deletion can cascade and break OrbitalSync. - -### [HIGH] gossamer-bridge-pattern - -**Rule:** Gossamer commands in src/commands/ are invoke wrappers only — do not put business logic there - -**Why:** Business logic belongs in Update.res. Commands are thin bridges to the Gossamer backend. - -### [CRITICAL] binary-star-model - -**Rule:** The Binary Star architecture (Panel-L symbolic + Panel-N neural + Panel-W world) is deliberate — do not flatten into a single panel type - -**Why:** The three panel types serve fundamentally different roles. This is the core design of PanLL. - -### [CRITICAL] rescript-core-team - -**Rule:** The project owner is on the ReScript core team — do not suggest migrating away from ReScript - -**Why:** ReScript is not a temporary choice. The owner contributes to ReScript itself. - -## Protected Files and Directories - -Do NOT delete, reorganise, or replace these without explicit user approval: - -| Path | Reason | -|------|--------| -| `src/tea/` | Custom TEA runtime — 18 modules. NEVER replace with rescript-tea. | -| `src/Model.res` | Single state tree — all application state lives here | -| `src/Msg.res` | Message type definitions — the TEA message catalogue | -| `src/Update.res` | State transition kernel — ~7500 lines, the heart of PanLL | -| `src/View.res` | Root view renderer | -| `src/App.res` | Application entry point | -| `src/core/` | Core engines — AntiCrash, OrbitalSync, Contractiles, TypeLLEngine, VabEngine | -| `src/components/` | 106 panel views — do not bulk-delete | -| `src/commands/` | Gossamer bridge commands — thin wrappers only | -| `src/modules/` | Module registry + TypeLLService — cross-panel type intelligence | -| `src-gossamer/` | Rust backend (WebKitGTK) — Gossamer desktop integration | -| `beam/` | Elixir/BEAM API layer | -| `tests/` | 979 tests, 41 suites — never delete tests | -| `.machine_readable/` | Canonical location for A2ML state files — MUST stay here | -| `coordination.k9` | This file — source of truth for AI coordination | - -## Architecture Decisions (Deliberate) - -These choices may look unusual but are intentional: - -### gossamer-not-tauri - -**Decision:** Gossamer (Zig + WebKitGTK) is the desktop backend — migration from Tauri 2.0 is complete - -**Why:** Gossamer is the hyperpolymath desktop runtime. Tauri was used previously but replaced. - -**Rejected alternatives:** Tauri 2.0, Electron, native GTK - -### custom-tea-not-rescript-tea - -**Decision:** Custom TEA runtime (src/tea/, 18 modules) instead of the rescript-tea library - -**Why:** PanLL needs Anti-Crash integration, OrbitalSync, Vexometer hooks, and panel lifecycle — none available in rescript-tea - -**Rejected alternatives:** rescript-tea, Redux, MobX, React hooks pattern - -### deno-only-with-npm-specifiers - -**Decision:** Deno orchestrates everything; ReScript and Tailwind run via `npm:` specifiers in `deno.json` - -**Why:** Post panll#65: `package.json` + `package-lock.json` deleted; ReScript compiles via `deno run -A --allow-scripts=npm:rescript npm:rescript@^12.0.0 build`, Tailwind via `deno run -A npm:tailwindcss`. No npm CLI invocation. Do not extend npm's role. - -### binary-star - -**Decision:** Three panel types: Panel-L (symbolic/human), Panel-N (neural/machine), Panel-W (world/shared) - -**Why:** Neurosymbolic architecture requires clear separation of human reasoning, machine inference, and shared world state - -### vexometer-cognitive-load - -**Decision:** Vexometer monitors operator stress and adapts UI detail density - -**Why:** HTI (Human-Tool Interaction) principle — the IDE adapts to the human, not vice versa - -### anticrash-circuit-breaker - -**Decision:** Anti-Crash validates all neural tokens before they enter the symbolic pipeline - -**Why:** Safety boundary between neural and symbolic systems — prevents hallucinated code from corrupting state - -## Do NOT Create - -These files, patterns, or systems must NOT be introduced: - -- ****/*.ts** — TypeScript is banned — use ReScript -- **Dockerfile** — Use Containerfile (Podman, not Docker) -- ****/*.py** — Python is banned — use ReScript, Rust, or Elixir -- **A replacement TEA runtime or state management library** — src/tea/ is the TEA runtime — it is custom, deliberate, and must not be replaced -- **REST API endpoints parallel to existing Groove protocol endpoints** — Groove is the inter-service communication protocol — do not create REST alternatives -- **A new panel type beyond Panel-L, Panel-N, Panel-W** — Binary Star model has exactly three types — adding more would break OrbitalSync -- **Direct Tauri imports or tauri.conf.json** — Tauri migration to Gossamer is complete — do not reintroduce - -## Terminology - -Use the correct terms for this project: - -- Say **"panels"**, NOT "panes", "tabs", "windows" - - PanLL UI elements are always called panels — this is enforced everywhere -- Say **"Binary Star"**, NOT "dual-pane", "split-view", "two-panel" - - The architectural model is Binary Star (Panel-L + Panel-N orbiting Panel-W) -- Say **"Anti-Crash"**, NOT "validator", "sanitizer", "filter" - - The neural token validation system is called Anti-Crash -- Say **"Vexometer"**, NOT "stress meter", "load indicator", "fatigue tracker" - - The cognitive load monitoring system is called Vexometer -- Say **"OrbitalSync"**, NOT "state sync", "panel sync", "sync engine" - - The multi-panel state coherence system is called OrbitalSync - -## Port Assignments - -| Service | Port | -|---------|------| -| dev-server | 8000 | -| echidna | 9000 | -| verisim | 8080 | -| boj-server | 7700 | -| typell | 7800 | - -## Ecosystem Context - -**Depends on:** -- **gossamer** — Desktop backend runtime (Zig + WebKitGTK) -- **verisim** — Persistent storage layer -- **typell** — Type intelligence engine — cross-panel type checking -- **boj-server** — MCP server — all external tool integration - -**Consumed by:** -- **idaptik** — Uses PanLL as level editor for game content - -**Related projects:** -- **echidna** — Proof engine — formal verification integration -- **hypatia** — Neurosymbolic CI/CD scanning -- **panic-attack** — Security scanning tool -- **gitbot-fleet** — Bot orchestration (rhodibot, echidnabot, etc.) -- **proven** — Formally verified alternatives library diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc new file mode 100644 index 00000000..9b836fb2 --- /dev/null +++ b/GOVERNANCE.adoc @@ -0,0 +1,60 @@ +== Governance + +=== Overview + +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. + +=== Roles and Responsibilities + +==== Maintainers + +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support + +==== Contributors + +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed + +=== Decision Making + +==== Minor Changes + +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates + +==== Major Changes + +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers + +==== Breaking Changes + +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide + +=== Code of Conduct + +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. + +=== Communication + +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions + +=== Licensing + +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. + +''''' + +_Last updated: 2026-07-18_ diff --git a/GOVERNANCE.md b/GOVERNANCE.md deleted file mode 100644 index e27364c7..00000000 --- a/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/GROOVE_PANLL_RESEARCH_SUMMARY.adoc b/GROOVE_PANLL_RESEARCH_SUMMARY.adoc new file mode 100644 index 00000000..042e8a59 --- /dev/null +++ b/GROOVE_PANLL_RESEARCH_SUMMARY.adoc @@ -0,0 +1,476 @@ +== Groove Protocol & PanLL Research Summary + +____ +*HISTORICAL (2024, Mistral-Vibe era) — SUPERSEDED.* Kept for provenance; +do not implement from this document. The groove dialect described here +(port 9000, `+groove_version+` probing, capabilities-as-shown) predates +the canonical protocol, and the five-mode "`transmutation spectrum`" was +the precursor intuition of what is now the cleave dial. Current canon: +the joinery naming ADR (groove `+docs/decisions/0009+`), groove +`+spec/SPEC.adoc+` (v0.3: leases §4.6, signed manifests §2.1.5), +`+cleave/docs/KERNEL.adoc+` + `+RANKED-OWNERSHIP-CLEAVE.adoc+` v0.3 (the +dial, soft/hard as lease modes, posture TS-1..7), and +`+cleave/docs/architecture/THE-JOINERY.adoc+` (orientation). +____ + +*Date:* 2024-04-14 *Researcher:* Mistral Vibe *Purpose:* Understand +Groove Protocol and PanLL panel/plugin development for eNSAID +integration + +=== Executive Summary + +This research examines the Groove Protocol (service discovery) and PanLL +(eNSAID cognitive-relief layer) to inform the development of +discipline-specific security analyzers within an ambient, neurosymbolic +development environment. + +=== Groove Protocol Analysis + +==== Core Concepts + +*Groove Protocol* is a service discovery mechanism that enables +automatic detection and integration of capabilities across the +hyperpolymath ecosystem. It uses standard HTTP probing on well-known +endpoints to advertise and discover services. + +==== Key Components + +===== 1. Discovery Mechanism + +* *Endpoint:* `+GET /.well-known/groove+` +* *Response:* JSON capability manifest +* *Port:* Typically 9000 (configurable) +* *Probing:* Standard port scanning by groove-aware systems + +===== 2. Manifest Structure + +[source,json] +---- +{ + "groove_version": "1", + "service_id": "echidna", + "service_version": "0.1.0", + "capabilities": { + "theorem-proving": { + "type": "theorem-proving", + "description": "Multi-backend theorem proving", + "protocol": "http", + "endpoint": "/api/prove", + "requires_auth": false, + "panel_compatible": true + } + }, + "consumes": ["octad-storage", "scanning"], + "endpoints": { + "health": "/health", + "groove": "/.well-known/groove", + "graphql": "/graphql" + }, + "health": "/health", + "applicability": ["individual", "team"] +} +---- + +===== 3. Implementation Example (Rust) + +[source,rust] +---- +// From echidna/src/rust/groove.rs +pub const GROOVE_PORT: u16 = 9000; + +async fn groove_manifest() -> Json { + Json(manifest()) +} + +async fn health_check() -> Json { + Json(json!({"status": "ok", "service": "echidna"})) +} + +pub fn router() -> Router { + Router::new() + .route("/.well-known/groove", get(groove_manifest)) + .route("/health", get(health_check)) +} +---- + +==== Groove Ecosystem + +*Groove-Aware Systems:* - Gossamer (core framework) - PanLL (eNSAID +layer) - Hypatia (security scanner) - ECHIDNA (theorem prover) - +VeriSimDB (octad storage) + +*Key Features:* - *Automatic Discovery:* Services announce capabilities +via standard endpoint - *Capability Negotiation:* Consumers find +services by probing known ports - *Health Checking:* Standard +`+/health+` endpoint for service status - *Panel Compatibility:* +Services can integrate with PanLL panels + +==== Groove Protocol Benefits + +[arabic] +. *Decentralized Discovery:* No central registry needed +. *Standardized Interface:* Consistent manifest format +. *Automatic Integration:* Services automatically appear in groove-aware +UIs +. *Health Monitoring:* Built-in service status checking +. *Extensible:* New capability types can be added without breaking +changes + +=== PanLL Analysis + +==== Core Philosophy + +*PanLL (Parallel)* is the *eNSAID* (Environmental Neurosymbolic Support +for Ambient Interface Design) - a cognitive-relief layer that reduces +friction in human-machine interaction. + +*Key Principle:* "`Reduce the amount of unnecessary thinking required to +make progress`" + +==== Architecture Overview + +.... +┌───────────────────────────────────────────────────────┐ +│ PanLL eNSAID Layer │ +├───────────────────┬───────────────────┬─────────────────┤ +│ Cognitive Relief │ Panel System │ Clade Portal │ +└─────────┬─────────┴─────────┬─────────┴─────────┬───────┘ + │ │ │ + ▼ ▼ ▼ +┌─────────────────┐ ┌─────────────┐ ┌─────────────────┐ +│Reduced Friction │Visual Interface│Service Discovery│ +│Lower Overhead │Clade Management│Groove Integration│ +│Smoother Workflow│Task Automation │Capability Browser│ +└─────────────────┘ └─────────────┘ └─────────────────┘ +.... + +==== Panel System Architecture + +===== 1. Clade-Based Panels + +*Clade Definition:* A modular component that provides specific +functionality + +*Example (BoJ Clade):* + +[source,a2ml] +---- +[clade] +id = "boj" +name = "BoJ — Bundle of Joy" +kind = "bridge" +version = "1.0.0" + +[clade-capabilities] +capabilities = [ + "CartridgeList", "CartridgeLoad", "CartridgeUnload", + "HealthCheck", "TopologyView", "UmojaFederation" +] + +[clade-panel] +panel-id = 39 +source-repo = "panll" +model = "src/model/BojModel.res" +engine = "src/core/BojEngine.res" +view = "src/components/Boj.res" +tabs = ["Dashboard", "Cartridges", "Topology", "Federation", "Invoke"] +---- + +===== 2. Panel Structure + +.... +panll/src/ +├── model/ # Data models (BojModel.res) +├── core/ # Business logic (BojEngine.res) +├── commands/ # User actions (BojCmd.res) +├── components/ # UI components (Boj.res) +├── modules/ # Reusable modules +└── generated/ # Auto-generated code +.... + +===== 3. Development Workflow + +[arabic] +. *Define Clade:* Create `+.a2ml+` file describing capabilities +. *Implement Model:* Define data structures and state +. *Build Engine:* Implement business logic +. *Create Commands:* Define user actions +. *Design View:* Build UI components +. *Register Panel:* Add to PanLL panel-clades directory + +==== Panel Development Example + +*BoJ Panel Structure:* - *Model:* `+src/model/BojModel.res+` - State +management - *Engine:* `+src/core/BojEngine.res+` - Business logic - +*Commands:* `+src/commands/BojCmd.res+` - User actions - *View:* +`+src/components/Boj.res+` - UI (887 lines, 5 tabs) + +==== PanLL Features + +[arabic] +. *Clade Portal:* Browser for discovering and loading clades +. *Panel Management:* Dynamic panel loading/unloading +. *Task Automation:* Reduce manual configuration +. *Visual Workflow:* Intuitive interfaces for complex tasks +. *Groove Integration:* Automatic service discovery +. *Accessibility:* Keyboard navigation, screen reader support + +=== Integration Opportunities + +==== 1. Groove Protocol Integration + +*Discipline Analyzers as Groove Services:* + +[source,json] +---- +{ + "groove_version": "1", + "service_id": "discipline-analyzers", + "service_version": "0.1.0", + "capabilities": { + "affine-analysis": { + "type": "code-analysis", + "description": "Affine resource discipline analysis", + "protocol": "http", + "endpoint": "/api/analyze/affine", + "requires_auth": false, + "panel_compatible": true + }, + "linear-enforcement": { + "type": "code-analysis", + "description": "Linear discipline enforcement", + "protocol": "http", + "endpoint": "/api/analyze/linear", + "requires_auth": false, + "panel_compatible": true + } + }, + "consumes": ["octad-storage"], + "endpoints": { + "health": "/health", + "groove": "/.well-known/groove" + }, + "health": "/health", + "applicability": ["individual", "team"] +} +---- + +==== 2. PanLL Panel Development + +*Discipline Analyzer Panel:* + +[source,a2ml] +---- +[clade] +id = "discipline-analyzers" +name = "Discipline Analyzers" +kind = "analysis" +version = "0.1.0" + +[clade-capabilities] +capabilities = [ + "AffineAnalysis", "LinearEnforcement", "DyadicTransition", + "EffectValidation", "RuntimeMonitoring", "FormalVerification" +] + +[clade-panel] +panel-id = 42 +source-repo = "discipline-analyzers" +model = "src/panel/DisciplineModel.res" +engine = "src/panel/DisciplineEngine.res" +view = "src/panel/DisciplineView.res" +tabs = ["Affine", "Linear", "Dyadic", "Effects", "Runtime", "Formal"] +---- + +==== 3. eNSAID Integration Points + +[arabic] +. *Cognitive Relief:* +* Automate discipline analysis +* Reduce manual security checking overhead +* Provide real-time feedback +. *Ambient Interface:* +* Runtime monitoring dashboard +* Visual discipline flow diagrams +* Context-aware suggestions +. *Neurosymbolic Integration:* +* LLM-assisted migration suggestions +* Formal verification guidance +* Adaptive analysis based on context + +=== Development Strategy + +==== Phase 1: Groove Service Implementation + +[arabic] +. *Add Groove Endpoint* to DisciplineAnalyzers +* Implement `+/.well-known/groove+` handler +* Create health check endpoint +* Generate capability manifest +. *HTTP API Design* +* `+/api/analyze/affine+` - Affine analysis +* `+/api/analyze/linear+` - Linear enforcement +* `+/api/analyze/dyadic+` - Transition analysis +* `+/api/monitor/runtime+` - Runtime monitoring +. *Service Registration* +* Add to PanLL clade portal +* Configure automatic discovery +* Test groove probing + +==== Phase 2: PanLL Panel Development + +[arabic] +. *Panel Skeleton* +* Create `+DisciplineModel.res+` +* Implement `+DisciplineEngine.res+` +* Design `+DisciplineView.res+` +. *Clade Definition* +* Write `+.a2ml+` file +* Register capabilities +* Define panel structure +. *UI Integration* +* Add to PanLL panel-clades +* Test panel loading +* Implement tab navigation + +==== Phase 3: eNSAID Features + +[arabic] +. *Cognitive Relief* +* Automate common analysis tasks +* Provide one-click fixes +* Reduce configuration overhead +. *Ambient Feedback* +* Real-time discipline monitoring +* Visual violation indicators +* Context-sensitive help +. *Neurosymbolic Enhancement* +* LLM-powered migration suggestions +* Formal verification assistance +* Adaptive analysis levels + +=== Technical Recommendations + +==== Groove Implementation + +[source,julia] +---- +# In DisciplineAnalyzers.jl +using HTTP +using JSON + +function groove_manifest_handler(req::HTTP.Request) + manifest = Dict( + "groove_version" => "1", + "service_id" => "discipline-analyzers", + "capabilities" => Dict( + "affine-analysis" => Dict( + "type" => "code-analysis", + "description" => "Affine resource discipline analysis", + "endpoint" => "/api/analyze/affine", + "panel_compatible" => true + ) + ) + ) + return HTTP.Response(200, JSON.json(manifest)) +end + +function health_handler(req::HTTP.Request) + return HTTP.Response(200, JSON.json(Dict("status" => "ok"))) +end + +function start_groove_server(port::Int=9001) + router = HTTP.Router() + HTTP.register!(router, "GET", "/.well-known/groove", groove_manifest_handler) + HTTP.register!(router, "GET", "/health", health_handler) + + server = HTTP.serve(router, "127.0.0.1", port) + @info "Groove server started on port $port" + return server +end +---- + +==== PanLL Panel Structure + +[source,rescript] +---- +// src/panel/DisciplineModel.res +module DisciplineModel = { + type state = { + currentTab: string, + affineResults: option, + linearResults: option, + violations: array + } + + let initialState = { + currentTab: "Affine", + affineResults: None, + linearResults: None, + violations: [] + } +} +---- + +=== Research Findings Summary + +==== Groove Protocol + +✅ *Mature and Standardized* - Well-defined discovery mechanism ✅ +*Widely Adopted* - Used across hyperpolymath ecosystem ✅ *Easy +Integration* - Simple HTTP-based interface ✅ *Panel Compatible* - +Designed for PanLL integration + +==== PanLL eNSAID + +✅ *Clear Architecture* - Modular clade-based system ✅ *Development +Framework* - Established patterns and conventions ✅ *Cognitive Focus* - +Designed to reduce friction ✅ *Extensible* - Easy to add new panels + +==== Integration Potential + +✅ *High Compatibility* - Discipline analyzers fit well with +Groove/PanLL ✅ *Cognitive Benefits* - Aligns with eNSAID goals ✅ +*Technical Feasibility* - Clear implementation path ✅ *Ecosystem Value* +- Fills gap in security analysis tooling + +=== Next Steps + +==== Immediate Actions + +[arabic] +. *Implement Groove Endpoint* in DisciplineAnalyzers +. *Create Basic Panel Skeleton* for PanLL integration +. *Design HTTP API* for discipline analysis services +. *Write Clade Definition* for discipline analyzers + +==== Short-term Goals + +[arabic] +. *Complete Groove Service* with all capabilities +. *Build Functional Panel* with basic analysis views +. *Integrate with PanLL* clade portal +. *Test Discovery* mechanism + +==== Long-term Vision + +[arabic] +. *Full eNSAID Integration* with cognitive relief features +. *Neurosymbolic Enhancement* with LLM assistance +. *Ambient Monitoring* with real-time feedback +. *Ecosystem Adoption* across hyperpolymath projects + +=== Conclusion + +The research confirms that Groove Protocol and PanLL provide an +excellent foundation for integrating discipline-specific security +analyzers into the hyperpolymath ecosystem. The Groove service discovery +mechanism enables seamless integration, while PanLL’s eNSAID philosophy +ensures the tools will provide genuine cognitive relief to developers. + +*Recommendation:* Proceed with Groove service implementation and PanLL +panel development as planned, leveraging the existing patterns and +infrastructure to create a cohesive, ambient development experience. + +*Maintainers:* @hyperpolymath/core-team *Research Lead:* Mistral Vibe +*Next Review:* 2024-04-21 (Implementation progress) diff --git a/GROOVE_PANLL_RESEARCH_SUMMARY.md b/GROOVE_PANLL_RESEARCH_SUMMARY.md deleted file mode 100644 index 1fac42ee..00000000 --- a/GROOVE_PANLL_RESEARCH_SUMMARY.md +++ /dev/null @@ -1,446 +0,0 @@ -# Groove Protocol & PanLL Research Summary - -> **HISTORICAL (2024, Mistral-Vibe era) — SUPERSEDED.** Kept for provenance; -> do not implement from this document. The groove dialect described here -> (port 9000, `groove_version` probing, capabilities-as-shown) predates the -> canonical protocol, and the five-mode "transmutation spectrum" was the -> precursor intuition of what is now the cleave dial. Current canon: -> the joinery naming ADR (groove `docs/decisions/0009`), groove -> `spec/SPEC.adoc` (v0.3: leases §4.6, signed manifests §2.1.5), -> `cleave/docs/KERNEL.adoc` + `RANKED-OWNERSHIP-CLEAVE.adoc` v0.3 (the -> dial, soft/hard as lease modes, posture TS-1..7), and -> `cleave/docs/architecture/THE-JOINERY.adoc` (orientation). - - -**Date:** 2024-04-14 -**Researcher:** Mistral Vibe -**Purpose:** Understand Groove Protocol and PanLL panel/plugin development for eNSAID integration - -## Executive Summary - -This research examines the Groove Protocol (service discovery) and PanLL (eNSAID cognitive-relief layer) to inform the development of discipline-specific security analyzers within an ambient, neurosymbolic development environment. - -## Groove Protocol Analysis - -### Core Concepts - -**Groove Protocol** is a service discovery mechanism that enables automatic detection and integration of capabilities across the hyperpolymath ecosystem. It uses standard HTTP probing on well-known endpoints to advertise and discover services. - -### Key Components - -#### 1. Discovery Mechanism -- **Endpoint:** `GET /.well-known/groove` -- **Response:** JSON capability manifest -- **Port:** Typically 9000 (configurable) -- **Probing:** Standard port scanning by groove-aware systems - -#### 2. Manifest Structure - -```json -{ - "groove_version": "1", - "service_id": "echidna", - "service_version": "0.1.0", - "capabilities": { - "theorem-proving": { - "type": "theorem-proving", - "description": "Multi-backend theorem proving", - "protocol": "http", - "endpoint": "/api/prove", - "requires_auth": false, - "panel_compatible": true - } - }, - "consumes": ["octad-storage", "scanning"], - "endpoints": { - "health": "/health", - "groove": "/.well-known/groove", - "graphql": "/graphql" - }, - "health": "/health", - "applicability": ["individual", "team"] -} -``` - -#### 3. Implementation Example (Rust) - -```rust -// From echidna/src/rust/groove.rs -pub const GROOVE_PORT: u16 = 9000; - -async fn groove_manifest() -> Json { - Json(manifest()) -} - -async fn health_check() -> Json { - Json(json!({"status": "ok", "service": "echidna"})) -} - -pub fn router() -> Router { - Router::new() - .route("/.well-known/groove", get(groove_manifest)) - .route("/health", get(health_check)) -} -``` - -### Groove Ecosystem - -**Groove-Aware Systems:** -- Gossamer (core framework) -- PanLL (eNSAID layer) -- Hypatia (security scanner) -- ECHIDNA (theorem prover) -- VeriSimDB (octad storage) - -**Key Features:** -- **Automatic Discovery:** Services announce capabilities via standard endpoint -- **Capability Negotiation:** Consumers find services by probing known ports -- **Health Checking:** Standard `/health` endpoint for service status -- **Panel Compatibility:** Services can integrate with PanLL panels - -### Groove Protocol Benefits - -1. **Decentralized Discovery:** No central registry needed -2. **Standardized Interface:** Consistent manifest format -3. **Automatic Integration:** Services automatically appear in groove-aware UIs -4. **Health Monitoring:** Built-in service status checking -5. **Extensible:** New capability types can be added without breaking changes - -## PanLL Analysis - -### Core Philosophy - -**PanLL (Parallel)** is the **eNSAID** (Environmental Neurosymbolic Support for Ambient Interface Design) - a cognitive-relief layer that reduces friction in human-machine interaction. - -**Key Principle:** "Reduce the amount of unnecessary thinking required to make progress" - -### Architecture Overview - -``` -┌───────────────────────────────────────────────────────┐ -│ PanLL eNSAID Layer │ -├───────────────────┬───────────────────┬─────────────────┤ -│ Cognitive Relief │ Panel System │ Clade Portal │ -└─────────┬─────────┴─────────┬─────────┴─────────┬───────┘ - │ │ │ - ▼ ▼ ▼ -┌─────────────────┐ ┌─────────────┐ ┌─────────────────┐ -│Reduced Friction │Visual Interface│Service Discovery│ -│Lower Overhead │Clade Management│Groove Integration│ -│Smoother Workflow│Task Automation │Capability Browser│ -└─────────────────┘ └─────────────┘ └─────────────────┘ -``` - -### Panel System Architecture - -#### 1. Clade-Based Panels - -**Clade Definition:** A modular component that provides specific functionality - -**Example (BoJ Clade):** -```a2ml -[clade] -id = "boj" -name = "BoJ — Bundle of Joy" -kind = "bridge" -version = "1.0.0" - -[clade-capabilities] -capabilities = [ - "CartridgeList", "CartridgeLoad", "CartridgeUnload", - "HealthCheck", "TopologyView", "UmojaFederation" -] - -[clade-panel] -panel-id = 39 -source-repo = "panll" -model = "src/model/BojModel.res" -engine = "src/core/BojEngine.res" -view = "src/components/Boj.res" -tabs = ["Dashboard", "Cartridges", "Topology", "Federation", "Invoke"] -``` - -#### 2. Panel Structure - -``` -panll/src/ -├── model/ # Data models (BojModel.res) -├── core/ # Business logic (BojEngine.res) -├── commands/ # User actions (BojCmd.res) -├── components/ # UI components (Boj.res) -├── modules/ # Reusable modules -└── generated/ # Auto-generated code -``` - -#### 3. Development Workflow - -1. **Define Clade:** Create `.a2ml` file describing capabilities -2. **Implement Model:** Define data structures and state -3. **Build Engine:** Implement business logic -4. **Create Commands:** Define user actions -5. **Design View:** Build UI components -6. **Register Panel:** Add to PanLL panel-clades directory - -### Panel Development Example - -**BoJ Panel Structure:** -- **Model:** `src/model/BojModel.res` - State management -- **Engine:** `src/core/BojEngine.res` - Business logic -- **Commands:** `src/commands/BojCmd.res` - User actions -- **View:** `src/components/Boj.res` - UI (887 lines, 5 tabs) - -### PanLL Features - -1. **Clade Portal:** Browser for discovering and loading clades -2. **Panel Management:** Dynamic panel loading/unloading -3. **Task Automation:** Reduce manual configuration -4. **Visual Workflow:** Intuitive interfaces for complex tasks -5. **Groove Integration:** Automatic service discovery -6. **Accessibility:** Keyboard navigation, screen reader support - -## Integration Opportunities - -### 1. Groove Protocol Integration - -**Discipline Analyzers as Groove Services:** - -```json -{ - "groove_version": "1", - "service_id": "discipline-analyzers", - "service_version": "0.1.0", - "capabilities": { - "affine-analysis": { - "type": "code-analysis", - "description": "Affine resource discipline analysis", - "protocol": "http", - "endpoint": "/api/analyze/affine", - "requires_auth": false, - "panel_compatible": true - }, - "linear-enforcement": { - "type": "code-analysis", - "description": "Linear discipline enforcement", - "protocol": "http", - "endpoint": "/api/analyze/linear", - "requires_auth": false, - "panel_compatible": true - } - }, - "consumes": ["octad-storage"], - "endpoints": { - "health": "/health", - "groove": "/.well-known/groove" - }, - "health": "/health", - "applicability": ["individual", "team"] -} -``` - -### 2. PanLL Panel Development - -**Discipline Analyzer Panel:** - -```a2ml -[clade] -id = "discipline-analyzers" -name = "Discipline Analyzers" -kind = "analysis" -version = "0.1.0" - -[clade-capabilities] -capabilities = [ - "AffineAnalysis", "LinearEnforcement", "DyadicTransition", - "EffectValidation", "RuntimeMonitoring", "FormalVerification" -] - -[clade-panel] -panel-id = 42 -source-repo = "discipline-analyzers" -model = "src/panel/DisciplineModel.res" -engine = "src/panel/DisciplineEngine.res" -view = "src/panel/DisciplineView.res" -tabs = ["Affine", "Linear", "Dyadic", "Effects", "Runtime", "Formal"] -``` - -### 3. eNSAID Integration Points - -1. **Cognitive Relief:** - - Automate discipline analysis - - Reduce manual security checking overhead - - Provide real-time feedback - -2. **Ambient Interface:** - - Runtime monitoring dashboard - - Visual discipline flow diagrams - - Context-aware suggestions - -3. **Neurosymbolic Integration:** - - LLM-assisted migration suggestions - - Formal verification guidance - - Adaptive analysis based on context - -## Development Strategy - -### Phase 1: Groove Service Implementation - -1. **Add Groove Endpoint** to DisciplineAnalyzers - - Implement `/.well-known/groove` handler - - Create health check endpoint - - Generate capability manifest - -2. **HTTP API Design** - - `/api/analyze/affine` - Affine analysis - - `/api/analyze/linear` - Linear enforcement - - `/api/analyze/dyadic` - Transition analysis - - `/api/monitor/runtime` - Runtime monitoring - -3. **Service Registration** - - Add to PanLL clade portal - - Configure automatic discovery - - Test groove probing - -### Phase 2: PanLL Panel Development - -1. **Panel Skeleton** - - Create `DisciplineModel.res` - - Implement `DisciplineEngine.res` - - Design `DisciplineView.res` - -2. **Clade Definition** - - Write `.a2ml` file - - Register capabilities - - Define panel structure - -3. **UI Integration** - - Add to PanLL panel-clades - - Test panel loading - - Implement tab navigation - -### Phase 3: eNSAID Features - -1. **Cognitive Relief** - - Automate common analysis tasks - - Provide one-click fixes - - Reduce configuration overhead - -2. **Ambient Feedback** - - Real-time discipline monitoring - - Visual violation indicators - - Context-sensitive help - -3. **Neurosymbolic Enhancement** - - LLM-powered migration suggestions - - Formal verification assistance - - Adaptive analysis levels - -## Technical Recommendations - -### Groove Implementation - -```julia -# In DisciplineAnalyzers.jl -using HTTP -using JSON - -function groove_manifest_handler(req::HTTP.Request) - manifest = Dict( - "groove_version" => "1", - "service_id" => "discipline-analyzers", - "capabilities" => Dict( - "affine-analysis" => Dict( - "type" => "code-analysis", - "description" => "Affine resource discipline analysis", - "endpoint" => "/api/analyze/affine", - "panel_compatible" => true - ) - ) - ) - return HTTP.Response(200, JSON.json(manifest)) -end - -function health_handler(req::HTTP.Request) - return HTTP.Response(200, JSON.json(Dict("status" => "ok"))) -end - -function start_groove_server(port::Int=9001) - router = HTTP.Router() - HTTP.register!(router, "GET", "/.well-known/groove", groove_manifest_handler) - HTTP.register!(router, "GET", "/health", health_handler) - - server = HTTP.serve(router, "127.0.0.1", port) - @info "Groove server started on port $port" - return server -end -``` - -### PanLL Panel Structure - -```rescript -// src/panel/DisciplineModel.res -module DisciplineModel = { - type state = { - currentTab: string, - affineResults: option, - linearResults: option, - violations: array - } - - let initialState = { - currentTab: "Affine", - affineResults: None, - linearResults: None, - violations: [] - } -} -``` - -## Research Findings Summary - -### Groove Protocol -✅ **Mature and Standardized** - Well-defined discovery mechanism -✅ **Widely Adopted** - Used across hyperpolymath ecosystem -✅ **Easy Integration** - Simple HTTP-based interface -✅ **Panel Compatible** - Designed for PanLL integration - -### PanLL eNSAID -✅ **Clear Architecture** - Modular clade-based system -✅ **Development Framework** - Established patterns and conventions -✅ **Cognitive Focus** - Designed to reduce friction -✅ **Extensible** - Easy to add new panels - -### Integration Potential -✅ **High Compatibility** - Discipline analyzers fit well with Groove/PanLL -✅ **Cognitive Benefits** - Aligns with eNSAID goals -✅ **Technical Feasibility** - Clear implementation path -✅ **Ecosystem Value** - Fills gap in security analysis tooling - -## Next Steps - -### Immediate Actions -1. **Implement Groove Endpoint** in DisciplineAnalyzers -2. **Create Basic Panel Skeleton** for PanLL integration -3. **Design HTTP API** for discipline analysis services -4. **Write Clade Definition** for discipline analyzers - -### Short-term Goals -1. **Complete Groove Service** with all capabilities -2. **Build Functional Panel** with basic analysis views -3. **Integrate with PanLL** clade portal -4. **Test Discovery** mechanism - -### Long-term Vision -1. **Full eNSAID Integration** with cognitive relief features -2. **Neurosymbolic Enhancement** with LLM assistance -3. **Ambient Monitoring** with real-time feedback -4. **Ecosystem Adoption** across hyperpolymath projects - -## Conclusion - -The research confirms that Groove Protocol and PanLL provide an excellent foundation for integrating discipline-specific security analyzers into the hyperpolymath ecosystem. The Groove service discovery mechanism enables seamless integration, while PanLL's eNSAID philosophy ensures the tools will provide genuine cognitive relief to developers. - -**Recommendation:** Proceed with Groove service implementation and PanLL panel development as planned, leveraging the existing patterns and infrastructure to create a cohesive, ambient development experience. - -**Maintainers:** @hyperpolymath/core-team -**Research Lead:** Mistral Vibe -**Next Review:** 2024-04-21 (Implementation progress) \ No newline at end of file diff --git a/PROOF-NEEDS.adoc b/PROOF-NEEDS.adoc new file mode 100644 index 00000000..7157c5bc --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,50 @@ +== PROOF-NEEDS.md — panll + +=== Current State + +* *src/abi/*: YES — contains `+cartridge-schema.json+` and `+README.md+` +(no Idris2 files) +* *Dangerous patterns*: 0 in own code (164 references are all in UI +display code that shows believe_me/Admitted counts from OTHER repos) +* *LOC*: ~138,000 (ReScript + Rust) +* *ABI layer*: Schema-only, no Idris2 proofs + +=== What Needs Proving + +[width="100%",cols="51%,27%,22%",options="header",] +|=== +|Component |What |Why +|Cartridge schema validation |Cartridge loading validates against schema +correctly |Malformed cartridges crash panels or produce wrong output + +|PCC constraint propagator |Constraint propagation is sound and complete +|PanLL Constraint Checker is the build-time safety net + +|PCC ReScript scanner |Scanner correctly identifies all constraint +violations |Missed violations bypass safety checks + +|Verification Dashboard accuracy |Dashboard accurately reflects actual +proof state |Displaying wrong verification state gives false confidence + +|Provenance engine |Provenance tracking is complete and unforgeable +|Provenance gaps break audit trail + +|Gossamer coprocessor commands |Command dispatch is total (no unhandled +commands) |Unhandled commands silently fail + +|Wiring Inspector |Wiring analysis correctly identifies all connections +|Missing wires mean broken panel communication +|=== + +=== Recommended Prover + +*Idris2* — Replace schema-only ABI with proper Idris2 types. PCC +constraint propagation is a natural fit for formal verification. The +Rust PCC tool (`+tools/pcc/+`) should have soundness proofs. + +=== Priority + +*MEDIUM* — PanLL is the developer panel system. PCC soundness is the +highest-value proof (it checks constraints across the ecosystem). The +Verification Dashboard must accurately reflect proof state to avoid +false confidence. diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md deleted file mode 100644 index d94f05d1..00000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,28 +0,0 @@ -# PROOF-NEEDS.md — panll - -## Current State - -- **src/abi/**: YES — contains `cartridge-schema.json` and `README.md` (no Idris2 files) -- **Dangerous patterns**: 0 in own code (164 references are all in UI display code that shows believe_me/Admitted counts from OTHER repos) -- **LOC**: ~138,000 (ReScript + Rust) -- **ABI layer**: Schema-only, no Idris2 proofs - -## What Needs Proving - -| Component | What | Why | -|-----------|------|-----| -| Cartridge schema validation | Cartridge loading validates against schema correctly | Malformed cartridges crash panels or produce wrong output | -| PCC constraint propagator | Constraint propagation is sound and complete | PanLL Constraint Checker is the build-time safety net | -| PCC ReScript scanner | Scanner correctly identifies all constraint violations | Missed violations bypass safety checks | -| Verification Dashboard accuracy | Dashboard accurately reflects actual proof state | Displaying wrong verification state gives false confidence | -| Provenance engine | Provenance tracking is complete and unforgeable | Provenance gaps break audit trail | -| Gossamer coprocessor commands | Command dispatch is total (no unhandled commands) | Unhandled commands silently fail | -| Wiring Inspector | Wiring analysis correctly identifies all connections | Missing wires mean broken panel communication | - -## Recommended Prover - -**Idris2** — Replace schema-only ABI with proper Idris2 types. PCC constraint propagation is a natural fit for formal verification. The Rust PCC tool (`tools/pcc/`) should have soundness proofs. - -## Priority - -**MEDIUM** — PanLL is the developer panel system. PCC soundness is the highest-value proof (it checks constraints across the ecosystem). The Verification Dashboard must accurately reflect proof state to avoid false confidence. diff --git a/README.adoc.invariants.adoc b/README.adoc.invariants.adoc new file mode 100644 index 00000000..80a5d0eb --- /dev/null +++ b/README.adoc.invariants.adoc @@ -0,0 +1 @@ +== Invariant Path Scan: README.adoc diff --git a/README.adoc.invariants.md b/README.adoc.invariants.md deleted file mode 100644 index e9ccff7e..00000000 --- a/README.adoc.invariants.md +++ /dev/null @@ -1,2 +0,0 @@ -# Invariant Path Scan: README.adoc - diff --git a/RSR-COMPLIANCE-REPORT.adoc b/RSR-COMPLIANCE-REPORT.adoc new file mode 100644 index 00000000..d6e1fcaf --- /dev/null +++ b/RSR-COMPLIANCE-REPORT.adoc @@ -0,0 +1,199 @@ +== RSR-Template Compliance Report + +=== Executive Summary + +*Status*: ✅ FULLY COMPLIANT *Date*: 2026-04-07 *System*: PanLL Wizard +System + +=== Compliance Matrix + +==== 1. Repository Structure Compliance + +[width="100%",cols="43%,25%,32%",options="header",] +|=== +|Requirement |Status |Evidence +|SPDX License Headers |✅ PASS |All files have +`+SPDX-License-Identifier: CC-BY-SA-4.0+` + +|CHANGELOG.md |✅ PASS |Updated with wizard features + +|CODE_OF_CONDUCT.md |✅ PASS |Existing, unchanged + +|CONTRIBUTING.md |✅ PASS |Existing, unchanged + +|LICENSE |✅ PASS |Existing, unchanged + +|README.adoc |✅ PASS |Existing, unchanged +|=== + +==== 2. Git Configuration Compliance + +[cols=",,",options="header",] +|=== +|File |Status |Evidence +|.gitignore |✅ PASS |RSR-compliant, no changes needed +|.gitattributes |✅ PASS |RSR-compliant, includes ReScript settings +|.editorconfig |✅ PASS |RSR-compliant, proper indentation rules +|=== + +==== 3. Documentation Compliance + +[width="100%",cols="43%,25%,32%",options="header",] +|=== +|Requirement |Status |Evidence +|Standards Documentation |✅ PASS +|`+docs/standards/wizard/WIZARD-STANDARDS.adoc+` (8793 lines) + +|Architecture Diagrams |✅ PASS |Mermaid diagrams included + +|API Documentation |✅ PASS |Type signatures and interfaces documented + +|Test Documentation |✅ PASS |Test suite fully documented + +|Compliance Checklist |✅ PASS |Included in standards doc +|=== + +==== 4. Code Quality Compliance + +[width="100%",cols="43%,25%,32%",options="header",] +|=== +|Requirement |Status |Evidence +|SPDX Headers |✅ PASS |All 6 wizard files have proper headers +|Documentation Comments |✅ PASS |All modules have `+///+` documentation +|Type Safety |✅ PASS |Full ReScript type coverage +|Error Handling |✅ PASS |Comprehensive error management +|Test Coverage |✅ PASS |100% unit/integration test coverage +|=== + +==== 5. Wizard-Specific Compliance + +[width="100%",cols="39%,27%,34%",options="header",] +|=== +|Component |Status |Evidence +|WizardModel.res |✅ PASS |Template system, validation, proper types +|WizardMsg.res |✅ PASS |All message types documented +|UpdateWizard.res |✅ PASS |Real-time validation, test integration +|WizardCmd.res |✅ PASS |Command-based architecture +|WizardTest.res |✅ PASS |Comprehensive test suite +|UpdateWizardTest.res |✅ PASS |Test integration layer +|=== + +==== 6. Testing Compliance + +[cols=",,,",options="header",] +|=== +|Test Type |Status |Coverage |Evidence +|Unit Tests |✅ PASS |100% |4/4 core functions tested +|Integration Tests |✅ PASS |100% |2/2 workflows tested +|Performance Tests |✅ PASS |100% |2 benchmarks implemented +|Accessibility Tests |✅ PASS |100% |WCAG 2.3 compliance +|Test Reporting |✅ PASS |✅ |Automated report generation +|=== + +==== 7. Performance Compliance + +[cols=",,,",options="header",] +|=== +|Metric |Requirement |Measured |Status +|Template Application |<10ms |0.42ms |✅ PASS +|Capability Validation |<5ms |0.18ms |✅ PASS +|Dependency Validation |<5ms |0.15ms |✅ PASS +|Complete Flow |<50ms |8-12ms |✅ PASS +|=== + +==== 8. Governance Compliance + +[cols=",,",options="header",] +|=== +|Requirement |Status |Evidence +|Contractile Integration |✅ PASS |Built into generated components +|Groove Protocol Support |✅ PASS |Soft/Hard Groove patterns +|Trust Tier System |✅ PASS |Ayo/Trusted/HighAssurance/Governance +|Sandbox Policies |✅ PASS |Network/filesystem access controls +|=== + +==== 9. Accessibility Compliance + +[cols=",,",options="header",] +|=== +|WCAG 2.3 Requirement |Status |Evidence +|Keyboard Navigation |✅ PASS |Full keyboard support +|Screen Reader Support |✅ PASS |ARIA attributes +|Color Contrast |✅ PASS |4.5:1 minimum ratio +|Focus Management |✅ PASS |Logical tab order +|Error Identification |✅ PASS |Clear error messages +|=== + +=== File Inventory + +==== New Files Created (6) + +.... +src/commands/WizardCmd.res # 1772 lines - Command interface +src/core/Minter.res # 2146 lines - Unified minter +src/update/UpdateWizard.res # 4098 lines - Update logic +src/tests/WizardTest.res # 8793 lines - Test suite +src/update/UpdateWizardTest.res # 1128 lines - Test integration +docs/standards/wizard/WIZARD-STANDARDS.adoc # 8793 lines - Documentation +.... + +==== Modified Files (4) + +.... +src/model/WizardModel.res # +Template system + validation fields +src/msg/WizardMsg.res # +Test messages + template support +src/update/UpdateWizard.res # +Real-time validation + testing +CHANGELOG.md # +Wizard feature documentation +.... + +=== Compliance Verification + +==== Automated Checks + +* ✅ All files have SPDX license headers +* ✅ All modules have documentation comments +* ✅ All types are properly defined +* ✅ All error cases are handled +* ✅ Test coverage meets requirements +* ✅ Performance meets benchmarks + +==== Manual Verification + +* ✅ Architecture follows PanLL patterns +* ✅ Integration with existing systems verified +* ✅ Governance requirements met +* ✅ Accessibility standards implemented +* ✅ Documentation is comprehensive + +=== Recommendations + +==== Immediate Actions (None - All Compliant) + +* No critical compliance issues found +* All requirements met or exceeded + +==== Future Enhancements + +[arabic] +. *Advanced Templates*: Custom template creation UI +. *Groove Service Discovery*: Auto-detect available services +. *Contractile Validation*: Real-time governance checking +. *Progress Indicators*: Visual feedback during generation +. *State Persistence*: Save/load wizard sessions + +=== Conclusion + +The PanLL Wizard System is *FULLY COMPLIANT* with all RSR-Template +requirements: + +* ✅ *Repository Structure*: All required files present and properly +formatted +* ✅ *Code Quality*: SPDX headers, documentation, type safety +* ✅ *Testing*: 100% coverage across all test types +* ✅ *Performance*: All benchmarks exceeded +* ✅ *Governance*: Full contractile and Groove integration +* ✅ *Accessibility*: WCAG 2.3 compliance +* ✅ *Documentation*: Comprehensive standards and guides + +*Sign-off*: Ready for production deployment *Next Review*: Q3 2026 +(post-launch audit) *Maintainer*: PanLL Core Team diff --git a/RSR-COMPLIANCE-REPORT.md b/RSR-COMPLIANCE-REPORT.md deleted file mode 100644 index 805922e5..00000000 --- a/RSR-COMPLIANCE-REPORT.md +++ /dev/null @@ -1,163 +0,0 @@ -# RSR-Template Compliance Report - -## Executive Summary - -**Status**: ✅ FULLY COMPLIANT -**Date**: 2026-04-07 -**System**: PanLL Wizard System - -## Compliance Matrix - -### 1. Repository Structure Compliance - -| Requirement | Status | Evidence | -|-------------|--------|----------| -| SPDX License Headers | ✅ PASS | All files have `SPDX-License-Identifier: CC-BY-SA-4.0` | -| CHANGELOG.md | ✅ PASS | Updated with wizard features | -| CODE_OF_CONDUCT.md | ✅ PASS | Existing, unchanged | -| CONTRIBUTING.md | ✅ PASS | Existing, unchanged | -| LICENSE | ✅ PASS | Existing, unchanged | -| README.adoc | ✅ PASS | Existing, unchanged | - -### 2. Git Configuration Compliance - -| File | Status | Evidence | -|------|--------|----------| -| .gitignore | ✅ PASS | RSR-compliant, no changes needed | -| .gitattributes | ✅ PASS | RSR-compliant, includes ReScript settings | -| .editorconfig | ✅ PASS | RSR-compliant, proper indentation rules | - -### 3. Documentation Compliance - -| Requirement | Status | Evidence | -|-------------|--------|----------| -| Standards Documentation | ✅ PASS | `docs/standards/wizard/WIZARD-STANDARDS.adoc` (8793 lines) | -| Architecture Diagrams | ✅ PASS | Mermaid diagrams included | -| API Documentation | ✅ PASS | Type signatures and interfaces documented | -| Test Documentation | ✅ PASS | Test suite fully documented | -| Compliance Checklist | ✅ PASS | Included in standards doc | - -### 4. Code Quality Compliance - -| Requirement | Status | Evidence | -|-------------|--------|----------| -| SPDX Headers | ✅ PASS | All 6 wizard files have proper headers | -| Documentation Comments | ✅ PASS | All modules have `///` documentation | -| Type Safety | ✅ PASS | Full ReScript type coverage | -| Error Handling | ✅ PASS | Comprehensive error management | -| Test Coverage | ✅ PASS | 100% unit/integration test coverage | - -### 5. Wizard-Specific Compliance - -| Component | Status | Evidence | -|-----------|--------|----------| -| WizardModel.res | ✅ PASS | Template system, validation, proper types | -| WizardMsg.res | ✅ PASS | All message types documented | -| UpdateWizard.res | ✅ PASS | Real-time validation, test integration | -| WizardCmd.res | ✅ PASS | Command-based architecture | -| WizardTest.res | ✅ PASS | Comprehensive test suite | -| UpdateWizardTest.res | ✅ PASS | Test integration layer | - -### 6. Testing Compliance - -| Test Type | Status | Coverage | Evidence | -|-----------|--------|----------|----------| -| Unit Tests | ✅ PASS | 100% | 4/4 core functions tested | -| Integration Tests | ✅ PASS | 100% | 2/2 workflows tested | -| Performance Tests | ✅ PASS | 100% | 2 benchmarks implemented | -| Accessibility Tests | ✅ PASS | 100% | WCAG 2.3 compliance | -| Test Reporting | ✅ PASS | ✅ | Automated report generation | - -### 7. Performance Compliance - -| Metric | Requirement | Measured | Status | -|--------|-------------|----------|--------| -| Template Application | <10ms | 0.42ms | ✅ PASS | -| Capability Validation | <5ms | 0.18ms | ✅ PASS | -| Dependency Validation | <5ms | 0.15ms | ✅ PASS | -| Complete Flow | <50ms | 8-12ms | ✅ PASS | - -### 8. Governance Compliance - -| Requirement | Status | Evidence | -|-------------|--------|----------| -| Contractile Integration | ✅ PASS | Built into generated components | -| Groove Protocol Support | ✅ PASS | Soft/Hard Groove patterns | -| Trust Tier System | ✅ PASS | Ayo/Trusted/HighAssurance/Governance | -| Sandbox Policies | ✅ PASS | Network/filesystem access controls | - -### 9. Accessibility Compliance - -| WCAG 2.3 Requirement | Status | Evidence | -|----------------------|--------|----------| -| Keyboard Navigation | ✅ PASS | Full keyboard support | -| Screen Reader Support | ✅ PASS | ARIA attributes | -| Color Contrast | ✅ PASS | 4.5:1 minimum ratio | -| Focus Management | ✅ PASS | Logical tab order | -| Error Identification | ✅ PASS | Clear error messages | - -## File Inventory - -### New Files Created (6) -``` -src/commands/WizardCmd.res # 1772 lines - Command interface -src/core/Minter.res # 2146 lines - Unified minter -src/update/UpdateWizard.res # 4098 lines - Update logic -src/tests/WizardTest.res # 8793 lines - Test suite -src/update/UpdateWizardTest.res # 1128 lines - Test integration -docs/standards/wizard/WIZARD-STANDARDS.adoc # 8793 lines - Documentation -``` - -### Modified Files (4) -``` -src/model/WizardModel.res # +Template system + validation fields -src/msg/WizardMsg.res # +Test messages + template support -src/update/UpdateWizard.res # +Real-time validation + testing -CHANGELOG.md # +Wizard feature documentation -``` - -## Compliance Verification - -### Automated Checks -- ✅ All files have SPDX license headers -- ✅ All modules have documentation comments -- ✅ All types are properly defined -- ✅ All error cases are handled -- ✅ Test coverage meets requirements -- ✅ Performance meets benchmarks - -### Manual Verification -- ✅ Architecture follows PanLL patterns -- ✅ Integration with existing systems verified -- ✅ Governance requirements met -- ✅ Accessibility standards implemented -- ✅ Documentation is comprehensive - -## Recommendations - -### Immediate Actions (None - All Compliant) -- No critical compliance issues found -- All requirements met or exceeded - -### Future Enhancements -1. **Advanced Templates**: Custom template creation UI -2. **Groove Service Discovery**: Auto-detect available services -3. **Contractile Validation**: Real-time governance checking -4. **Progress Indicators**: Visual feedback during generation -5. **State Persistence**: Save/load wizard sessions - -## Conclusion - -The PanLL Wizard System is **FULLY COMPLIANT** with all RSR-Template requirements: - -- ✅ **Repository Structure**: All required files present and properly formatted -- ✅ **Code Quality**: SPDX headers, documentation, type safety -- ✅ **Testing**: 100% coverage across all test types -- ✅ **Performance**: All benchmarks exceeded -- ✅ **Governance**: Full contractile and Groove integration -- ✅ **Accessibility**: WCAG 2.3 compliance -- ✅ **Documentation**: Comprehensive standards and guides - -**Sign-off**: Ready for production deployment -**Next Review**: Q3 2026 (post-launch audit) -**Maintainer**: PanLL Core Team \ No newline at end of file diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 00000000..3c485efb --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,275 @@ +== Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. + +=== Table of Contents + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#cryptographic-requirements[Cryptographic Requirements] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/hyperpolymath/panll/security/advisories/new[Report a +Vulnerability] +. Click *"`Report a vulnerability`"* +. Complete the form with as much detail as possible +. Submit — we’ll receive a private notification + +This method ensures: + +* End-to-end encryption of your report +* Private discussion space for collaboration +* Coordinated disclosure tooling +* Automatic credit when the advisory is published + +==== Alternative: Encrypted Email + +If you cannot use GitHub Security Advisories, you may email us directly +at: + +*Email:* j.d.a.jewell@open.ac.uk + +____ +*⚠️ Important:* Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. +____ + +''''' + +=== Cryptographic Requirements + +When implementing cryptographic features in this project, the following +standards MUST be followed: + +Machine-readable policy: see `+.machine_readable/SECURITY.scm+` for the +canonical requirements list. + +==== Password Hashing + +* *Algorithm:* Argon2id +* *Parameters:* 512 MiB memory, 8 iterations, 4 lanes +* *Rationale:* Maximum resistance to GPU/ASIC attacks + +==== General Hashing + +* *Algorithm:* SHAKE3-512 (512-bit output) +* *Standard:* FIPS 202 +* *Use Cases:* Provenance, key derivation, long-term storage +* *Rationale:* Post-quantum secure + +==== Post-Quantum Signatures + +* *Primary:* Dilithium5-AES (hybrid) +* *Standard:* ML-DSA-87 (FIPS 204) +* *Fallback:* SPHINCS+ (conservative backup) +* *Rationale:* Hybrid with AES-256 for belt-and-suspenders security + +==== Post-Quantum Key Exchange + +* *Algorithm:* Kyber-1024 + SHAKE256-KDF +* *Standard:* ML-KEM-1024 (FIPS 203) +* *Fallback:* SPHINCS+ +* *Rationale:* Maximum PQ security level + +==== Classical Signatures + +* *Algorithm:* Ed448 + Dilithium5 (hybrid) +* *Fallback:* SPHINCS+ +* *⚠️ CRITICAL:* TERMINATE Ed25519/SHA-1 immediately - do not use in new +code + +==== Symmetric Encryption + +* *Algorithm:* XChaCha20-Poly1305 +* *Key Size:* 256-bit +* *Rationale:* Larger nonce space, quantum margin + +==== Key Derivation + +* *Algorithm:* HKDF-SHAKE512 +* *Standard:* FIPS 202 +* *Use:* All secret key material +* *Rationale:* Post-quantum secure KDF + +==== Random Number Generation + +* *Algorithm:* ChaCha20-DRBG +* *Seed Size:* 512-bit +* *Standard:* SP 800-90Ar1 +* *Use:* CSPRNG for deterministic, high-entropy needs + +==== Database Hashing + +* *Primary:* BLAKE3 (512-bit) +* *Long-term:* SHAKE3-512 +* *Rationale:* BLAKE3 for speed, SHAKE3-512 for archival with semantic +XML/ARIA tags + +==== Protocol Stack + +* *Required:* QUIC + HTTP/3 + IPv6 only +* *⚠️ TERMINATED:* HTTP/1.1, IPv4, SHA-1 (danger zone) + +==== Formal Verification + +* *Tool:* Idris2/Coq +* *Requirement:* All cryptographic primitives must have formal proofs +* *Rationale:* Proactive attestation and transparent logic + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +''''' + +=== Scope + +==== In Scope ✅ + +* This repository (`+hyperpolymath/panll+`) and all its code +* Official releases and packages published from this repository +* Documentation that could lead to security issues +* Build and deployment configurations in this repository +* Dependencies (report here, we’ll coordinate with upstream) + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* *Cryptographic weaknesses* (especially deviation from requirements +above) +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws in Anti-Crash validation + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +If you conduct security research in accordance with this policy: + +* ✅ We will not initiate legal action against you +* ✅ We will not report your activity to law enforcement +* ✅ We will work with you in good faith to resolve issues +* ✅ We consider your research authorised + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → "`Security +alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/hyperpolymath/panll/security/advisories[Security +Advisories] + +==== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Supported |Notes +|`+main+` branch |✅ Yes |Latest development +|Latest release |✅ Yes |Current stable +|Older versions |❌ No |Please upgrade +|=== + +''''' + +=== Security Best Practices + +When using PanLL eNSAID, we recommend: + +==== General + +* Keep dependencies up to date +* Use the latest stable release +* Subscribe to security notifications +* Review configuration against security documentation +* Follow principle of least privilege + +==== For Contributors + +* Never commit secrets, credentials, or API keys +* Use signed commits (`+git config commit.gpgsign true+`) +* Review dependencies before adding them +* Run security linters locally before pushing +* Report any concerns about existing code +* *NEVER use deprecated crypto:* Ed25519, SHA-1, MD5, DES, RC4 +* *ALWAYS use approved algorithms* from the Cryptographic Requirements +section + +''''' + +_Thank you for helping keep PanLL and its users safe._ 🛡️ + +''''' + +Last updated: 2026-02-09 · Policy version: 2.0.0 diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index fc4d6dc6..00000000 --- a/SECURITY.md +++ /dev/null @@ -1,231 +0,0 @@ -# Security Policy - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. - -## Table of Contents - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [Cryptographic Requirements](#cryptographic-requirements) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/hyperpolymath/panll/security/advisories/new) -2. Click **"Report a vulnerability"** -3. Complete the form with as much detail as possible -4. Submit — we'll receive a private notification - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- Coordinated disclosure tooling -- Automatic credit when the advisory is published - -### Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly at: - -**Email:** j.d.a.jewell@open.ac.uk - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## Cryptographic Requirements - -When implementing cryptographic features in this project, the following standards MUST be followed: - -Machine-readable policy: see `.machine_readable/SECURITY.scm` for the canonical requirements list. - -### Password Hashing -- **Algorithm:** Argon2id -- **Parameters:** 512 MiB memory, 8 iterations, 4 lanes -- **Rationale:** Maximum resistance to GPU/ASIC attacks - -### General Hashing -- **Algorithm:** SHAKE3-512 (512-bit output) -- **Standard:** FIPS 202 -- **Use Cases:** Provenance, key derivation, long-term storage -- **Rationale:** Post-quantum secure - -### Post-Quantum Signatures -- **Primary:** Dilithium5-AES (hybrid) -- **Standard:** ML-DSA-87 (FIPS 204) -- **Fallback:** SPHINCS+ (conservative backup) -- **Rationale:** Hybrid with AES-256 for belt-and-suspenders security - -### Post-Quantum Key Exchange -- **Algorithm:** Kyber-1024 + SHAKE256-KDF -- **Standard:** ML-KEM-1024 (FIPS 203) -- **Fallback:** SPHINCS+ -- **Rationale:** Maximum PQ security level - -### Classical Signatures -- **Algorithm:** Ed448 + Dilithium5 (hybrid) -- **Fallback:** SPHINCS+ -- **⚠️ CRITICAL:** TERMINATE Ed25519/SHA-1 immediately - do not use in new code - -### Symmetric Encryption -- **Algorithm:** XChaCha20-Poly1305 -- **Key Size:** 256-bit -- **Rationale:** Larger nonce space, quantum margin - -### Key Derivation -- **Algorithm:** HKDF-SHAKE512 -- **Standard:** FIPS 202 -- **Use:** All secret key material -- **Rationale:** Post-quantum secure KDF - -### Random Number Generation -- **Algorithm:** ChaCha20-DRBG -- **Seed Size:** 512-bit -- **Standard:** SP 800-90Ar1 -- **Use:** CSPRNG for deterministic, high-entropy needs - -### Database Hashing -- **Primary:** BLAKE3 (512-bit) -- **Long-term:** SHAKE3-512 -- **Rationale:** BLAKE3 for speed, SHAKE3-512 for archival with semantic XML/ARIA tags - -### Protocol Stack -- **Required:** QUIC + HTTP/3 + IPv6 only -- **⚠️ TERMINATED:** HTTP/1.1, IPv4, SHA-1 (danger zone) - -### Formal Verification -- **Tool:** Idris2/Coq -- **Requirement:** All cryptographic primitives must have formal proofs -- **Rationale:** Proactive attestation and transparent logic - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - ---- - -## Scope - -### In Scope ✅ - -- This repository (`hyperpolymath/panll`) and all its code -- Official releases and packages published from this repository -- Documentation that could lead to security issues -- Build and deployment configurations in this repository -- Dependencies (report here, we'll coordinate with upstream) - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- **Cryptographic weaknesses** (especially deviation from requirements above) -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws in Anti-Crash validation - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -If you conduct security research in accordance with this policy: - -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised - ---- - -## Security Updates - -### Receiving Updates - -To stay informed about security updates: - -- **Watch this repository**: Click "Watch" → "Custom" → "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/hyperpolymath/panll/security/advisories) - -### Supported Versions - -| Version | Supported | Notes | -|---------|-----------|-------| -| `main` branch | ✅ Yes | Latest development | -| Latest release | ✅ Yes | Current stable | -| Older versions | ❌ No | Please upgrade | - ---- - -## Security Best Practices - -When using PanLL eNSAID, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code -- **NEVER use deprecated crypto:** Ed25519, SHA-1, MD5, DES, RC4 -- **ALWAYS use approved algorithms** from the Cryptographic Requirements section - ---- - -*Thank you for helping keep PanLL and its users safe.* 🛡️ - ---- - -Last updated: 2026-02-09 · Policy version: 2.0.0 diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 00000000..e4dec64a --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,211 @@ +== TEST-NEEDS.md — panll + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +____ +Generated 2026-03-29 by punishing audit. Updated 2026-04-04 by CRG C +blitz. +____ + +=== Current State + +[width="100%",cols="50%,25%,25%",options="header",] +|=== +|Category |Count |Notes +|Unit tests |~120 |JS engine tests + Rust type tests + +|Integration |~6 |TEA framework: tea_app_test, tea_cmd_test, +tea_sub_test, tea_render_test + +|E2E |47 |e2e_panel_lifecycle_test.js (comprehensive lifecycle + TypeLL ++ cross-panel) + +|Benchmarks |35+ |engine_bench_test, tea_update_cycle_bench_test, +safedom_bench_test, panic_attack_bench_test + benches/panll_bench.js + +|P2P |23 |tests/p2p/tea_properties_test.mjs — TEA invariants, layout +no-overlap, IPC roundtrip + +|Aspect |36 |tests/aspect/security_test.mjs — IPC sanitation, plugin +sandboxing, redaction, XSS + +|Contract |30 |tests/contract/panel_contracts_test.mjs — C1-C9 +governance contracts + +|Reflexive |22 |tests/reflexive/manifest_test.mjs — manifest +consistency, export verification + +|Rust smoke |267 |All Rust tests pass (267 total). New smoke tests in: +security, capture, farm, minter, plaza, watcher, workspace, ai, +cloudguard, voicetag, hypatia +|=== + +*Source modules:* ~686 ReScript .res files. 116 Rust files (all +previously-untested crates now have smoke tests). + +=== What Was Added (2026-04-04 CRG C Blitz) + +==== Benchmarks + +* [x] `+benches/panll_bench.js+` — standalone bench file (4 groups × 8 +benches): +** TEA update cycle latency (NoOp baseline, AddConstraint, AntiCrash, +100-msg load) +** Panel creation/destruction time (Model.init, ResetAllPanels, registry +lookups, TogglePanel) +** IPC message throughput (PanelBus, JSON round-trips, AntiCrash +pipeline) +** Layout algorithm time vs panel count (1, 4, 9, 16, 36, 108 panels) +* [x] `+deno task bench+` added to deno.json + +==== P2P Property-Based Tests + +* [x] `+tests/p2p/tea_properties_test.mjs+` — 8 properties × 100 random +trials each: +** update(msg, model) always produces valid model shape +** TilingEngine.tile produces non-overlapping panels with positive +dimensions +** IPC JSON round-trip structural equality +** AntiCrash halted flag monotonicity +** Vexometer index non-decreasing +** Contractiles.evaluateAll never throws (totality) +** PanelRegistry findPanel/allPanels inverse consistency +** TypeLL serviceActive always boolean + +==== Aspect Tests + +* [x] `+tests/aspect/security_test.mjs+` — 36 tests: +** Panel IPC sanitization (malformed TAGs, null payloads, empty objects) +** Plugin sandboxing (CloudGuard cannot modify paneL, Farm cannot modify +cloudguard, etc.) +** Anti-Crash circuit breaker (processToken, checkSecurityConstraints) +** Redaction engine (Anthropic, OpenAI, GitHub tokens; idempotency; safe +content preservation) +** XSS/injection resistance (script tags, javascript: URIs, onerror, +onload, 1MB rejection) +** Governance range invariants (vexometer [0,1], orbital [0,1]) + +==== Contract Tests + +* [x] `+tests/contract/panel_contracts_test.mjs+` — 30 tests across 9 +contracts: +** C1: Orbital Stability Contract (threshold 0.7) +** C2: Vexation Ceiling Contract +** C3: Anti-Crash Quorum Contract (violations ≤ 10) +** C5: TypeLL Service Contract (queriesServed increments on Ok) +** C6: Panel Bus Contract (registry, topics, subscribers) +** C7: Model Initialisation Contract (11 default contractiles) +** C8: Governance Engine Contract +** C9: Contractiles Elasticity Adaptation Contract + +==== Reflexive Tests + +* [x] `+tests/reflexive/manifest_test.mjs+` — 22 tests: +** AI manifest claims vs PanelRegistry reality +** Panel count, ID uniqueness, clade coverage +** All core engine module exports verified (11 engines) +** TEA module export verification +** Model default values match documentation + +==== Rust Smoke Tests + +New `+#[cfg(test)]+` blocks added to crates that had zero tests: - +`+security/types.rs+` — 5 tests (RedactionPattern, DetectedSecret, +TrustfilePolicy, VaultKey) - `+capture/types.rs+` — 4 tests +(CaptureFormat, CaptureEntry, DemoPackage, DemoStep) - `+farm/types.rs+` +— 3 tests (FarmRepoEntry, FarmInventory, ManifestRepo) - +`+minter/types.rs+` — 5 tests (BackendKind, MintResult, WiringDetail, +BotFinding, Capability) - `+plaza/types.rs+` — 4 tests (ComplianceLevel, +ComplianceAudit, AdoptionStats, RepoScanResult) - `+watcher/types.rs+` — +4 tests (WatchEventKind, WatchEvent, WatcherStatus) - +`+workspace/types.rs+` — 6 tests (PanelPosition, Arrangement, +WorkspaceMode, SessionProtection, SystemInfo, PanelGroup) - +`+ai/types.rs+` — 6 tests (ProviderId, AiProvidersFile.defaults, +AiMessage, ProviderStatus, StreamChunk, ToolDefinition) - +`+cloudguard/types.rs+` — 3 tests (CfApiResponse success/failure parse, +CfApiError) - `+voicetag/commands.rs+` — 3 tests (empty MRI JSON +validity, suffix stripping, filename detection) - +`+hypatia/commands.rs+` — 2 tests merged (URL default, URL override) +into existing test module + +*Bug fixes (pre-existing):* - `+valence_shell/commands.rs+`: Fixed +`+valence_shell_checkpoint_restore+` called with 1 arg instead of 2 (in +existing tests) - `+valence_shell/commands.rs+`: Fixed `+map_or_else+` +type annotation (`+Ok::<_, Infallible>+`) + +*Total Rust tests after blitz: 267 (all passing)* + +=== What’s Still Missing + +==== P2P (Property-Based) Tests + +* [ ] Network topology: graph property tests (connectivity, acyclicity +where required) +* [ ] Security engine: policy evaluation property tests + +==== E2E Tests + +* [ ] Accessibility: keyboard navigation through all panel types +* [ ] Theme/variant: each visual theme renders correctly +* [ ] Gossamer integration: panel communication round-trips (requires +gossamer binary) + +==== Aspect Tests + +* *Concurrency:* No tests for concurrent panel operations, WebSocket +message ordering, subscription race conditions + +==== Build & Execution + +* [ ] ReScript build (686 modules — very slow, CI only) +* [ ] Elixir mix test (beam/ layer) + +==== Benchmarks (remaining) + +* [ ] Render time per panel type (requires compiled ReScript output + +DOM) +* [ ] Memory usage per panel count (long-running session simulation) + +==== Self-Tests + +* [ ] TEA framework self-test (model/view/update cycle with real DOM +render) +* [ ] Accessibility compliance check (WCAG — requires headless browser) + +==== CRITICAL GAPS (remaining after blitz) + +[width="100%",cols="20%,28%,21%,31%",options="header",] +|=== +|Area |Modules |Tests |Coverage +|Components (.res) |~200+ |0 direct |*0%* (requires ReScript build) +|Models (.res) |~100+ |0 direct |*0%* (requires ReScript build) +|Views (.res) |~100+ |0 direct |*0%* (requires ReScript build) +|TEA framework |~20 |4 |*20%* +|Rust crates |116 files |267 tests |*smoke coverage* +|=== + +=== CRG Grade Assessment + +*Before blitz:* D (3.8% coverage, 0 benchmarks, no taxonomy structure) +*After blitz:* C+ (Taxonomy structure complete, all taxonomy categories +populated, Rust smoke tests, 267 Rust tests passing) + +*CRG C requirements met:* - [x] Unit tests present (120+ JS + 267 Rust) +- [x] Smoke tests (all Rust crates have at least smoke coverage) - [x] +Build verification (cargo test: 267/267 pass) - [x] P2P property tests +(tea_properties_test.mjs) - [x] E2E tests (e2e_panel_lifecycle_test.js — +47 tests) - [x] Reflexive tests (manifest_test.mjs) - [x] Contract tests +(panel_contracts_test.mjs) - [x] Aspect tests (security_test.mjs) - [x] +Benchmarks baselined (benches/panll_bench.js + existing bench_test.js +files) + +*Next grade (B):* Requires 686 ReScript modules to build + coverage +measurement + 6 minimum A-tier targets. + +=== FAKE-FUZZ ALERT + +* `+tests/fuzz/placeholder.txt+` is a scorecard placeholder inherited +from rsr-template-repo — it does NOT provide real fuzz testing +* Replace with an actual fuzz harness (see +rsr-template-repo/tests/fuzz/README.adoc) or remove the file +* Priority: P2 — creates false impression of fuzz coverage diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 822e94dc..00000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,150 +0,0 @@ -# TEST-NEEDS.md — panll - -## CRG Grade: C — ACHIEVED 2026-04-04 - -> Generated 2026-03-29 by punishing audit. Updated 2026-04-04 by CRG C blitz. - -## Current State - -| Category | Count | Notes | -|-------------|-------|-------| -| Unit tests | ~120 | JS engine tests + Rust type tests | -| Integration | ~6 | TEA framework: tea_app_test, tea_cmd_test, tea_sub_test, tea_render_test | -| E2E | 47 | e2e_panel_lifecycle_test.js (comprehensive lifecycle + TypeLL + cross-panel) | -| Benchmarks | 35+ | engine_bench_test, tea_update_cycle_bench_test, safedom_bench_test, panic_attack_bench_test + benches/panll_bench.js | -| P2P | 23 | tests/p2p/tea_properties_test.mjs — TEA invariants, layout no-overlap, IPC roundtrip | -| Aspect | 36 | tests/aspect/security_test.mjs — IPC sanitation, plugin sandboxing, redaction, XSS | -| Contract | 30 | tests/contract/panel_contracts_test.mjs — C1-C9 governance contracts | -| Reflexive | 22 | tests/reflexive/manifest_test.mjs — manifest consistency, export verification | -| Rust smoke | 267 | All Rust tests pass (267 total). New smoke tests in: security, capture, farm, minter, plaza, watcher, workspace, ai, cloudguard, voicetag, hypatia | - -**Source modules:** ~686 ReScript .res files. 116 Rust files (all previously-untested crates now have smoke tests). - -## What Was Added (2026-04-04 CRG C Blitz) - -### Benchmarks -- [x] `benches/panll_bench.js` — standalone bench file (4 groups × 8 benches): - - TEA update cycle latency (NoOp baseline, AddConstraint, AntiCrash, 100-msg load) - - Panel creation/destruction time (Model.init, ResetAllPanels, registry lookups, TogglePanel) - - IPC message throughput (PanelBus, JSON round-trips, AntiCrash pipeline) - - Layout algorithm time vs panel count (1, 4, 9, 16, 36, 108 panels) -- [x] `deno task bench` added to deno.json - -### P2P Property-Based Tests -- [x] `tests/p2p/tea_properties_test.mjs` — 8 properties × 100 random trials each: - - update(msg, model) always produces valid model shape - - TilingEngine.tile produces non-overlapping panels with positive dimensions - - IPC JSON round-trip structural equality - - AntiCrash halted flag monotonicity - - Vexometer index non-decreasing - - Contractiles.evaluateAll never throws (totality) - - PanelRegistry findPanel/allPanels inverse consistency - - TypeLL serviceActive always boolean - -### Aspect Tests -- [x] `tests/aspect/security_test.mjs` — 36 tests: - - Panel IPC sanitization (malformed TAGs, null payloads, empty objects) - - Plugin sandboxing (CloudGuard cannot modify paneL, Farm cannot modify cloudguard, etc.) - - Anti-Crash circuit breaker (processToken, checkSecurityConstraints) - - Redaction engine (Anthropic, OpenAI, GitHub tokens; idempotency; safe content preservation) - - XSS/injection resistance (script tags, javascript: URIs, onerror, onload, 1MB rejection) - - Governance range invariants (vexometer [0,1], orbital [0,1]) - -### Contract Tests -- [x] `tests/contract/panel_contracts_test.mjs` — 30 tests across 9 contracts: - - C1: Orbital Stability Contract (threshold 0.7) - - C2: Vexation Ceiling Contract - - C3: Anti-Crash Quorum Contract (violations ≤ 10) - - C5: TypeLL Service Contract (queriesServed increments on Ok) - - C6: Panel Bus Contract (registry, topics, subscribers) - - C7: Model Initialisation Contract (11 default contractiles) - - C8: Governance Engine Contract - - C9: Contractiles Elasticity Adaptation Contract - -### Reflexive Tests -- [x] `tests/reflexive/manifest_test.mjs` — 22 tests: - - AI manifest claims vs PanelRegistry reality - - Panel count, ID uniqueness, clade coverage - - All core engine module exports verified (11 engines) - - TEA module export verification - - Model default values match documentation - -### Rust Smoke Tests -New `#[cfg(test)]` blocks added to crates that had zero tests: -- `security/types.rs` — 5 tests (RedactionPattern, DetectedSecret, TrustfilePolicy, VaultKey) -- `capture/types.rs` — 4 tests (CaptureFormat, CaptureEntry, DemoPackage, DemoStep) -- `farm/types.rs` — 3 tests (FarmRepoEntry, FarmInventory, ManifestRepo) -- `minter/types.rs` — 5 tests (BackendKind, MintResult, WiringDetail, BotFinding, Capability) -- `plaza/types.rs` — 4 tests (ComplianceLevel, ComplianceAudit, AdoptionStats, RepoScanResult) -- `watcher/types.rs` — 4 tests (WatchEventKind, WatchEvent, WatcherStatus) -- `workspace/types.rs` — 6 tests (PanelPosition, Arrangement, WorkspaceMode, SessionProtection, SystemInfo, PanelGroup) -- `ai/types.rs` — 6 tests (ProviderId, AiProvidersFile.defaults, AiMessage, ProviderStatus, StreamChunk, ToolDefinition) -- `cloudguard/types.rs` — 3 tests (CfApiResponse success/failure parse, CfApiError) -- `voicetag/commands.rs` — 3 tests (empty MRI JSON validity, suffix stripping, filename detection) -- `hypatia/commands.rs` — 2 tests merged (URL default, URL override) into existing test module - -**Bug fixes (pre-existing):** -- `valence_shell/commands.rs`: Fixed `valence_shell_checkpoint_restore` called with 1 arg instead of 2 (in existing tests) -- `valence_shell/commands.rs`: Fixed `map_or_else` type annotation (`Ok::<_, Infallible>`) - -**Total Rust tests after blitz: 267 (all passing)** - -## What's Still Missing - -### P2P (Property-Based) Tests -- [ ] Network topology: graph property tests (connectivity, acyclicity where required) -- [ ] Security engine: policy evaluation property tests - -### E2E Tests -- [ ] Accessibility: keyboard navigation through all panel types -- [ ] Theme/variant: each visual theme renders correctly -- [ ] Gossamer integration: panel communication round-trips (requires gossamer binary) - -### Aspect Tests -- **Concurrency:** No tests for concurrent panel operations, WebSocket message ordering, subscription race conditions - -### Build & Execution -- [ ] ReScript build (686 modules — very slow, CI only) -- [ ] Elixir mix test (beam/ layer) - -### Benchmarks (remaining) -- [ ] Render time per panel type (requires compiled ReScript output + DOM) -- [ ] Memory usage per panel count (long-running session simulation) - -### Self-Tests -- [ ] TEA framework self-test (model/view/update cycle with real DOM render) -- [ ] Accessibility compliance check (WCAG — requires headless browser) - -### CRITICAL GAPS (remaining after blitz) - -| Area | Modules | Tests | Coverage | -|------|---------|-------|----------| -| Components (.res) | ~200+ | 0 direct | **0%** (requires ReScript build) | -| Models (.res) | ~100+ | 0 direct | **0%** (requires ReScript build) | -| Views (.res) | ~100+ | 0 direct | **0%** (requires ReScript build) | -| TEA framework | ~20 | 4 | **20%** | -| Rust crates | 116 files | 267 tests | **smoke coverage** | - -## CRG Grade Assessment - -**Before blitz:** D (3.8% coverage, 0 benchmarks, no taxonomy structure) -**After blitz:** C+ (Taxonomy structure complete, all taxonomy categories populated, Rust smoke tests, 267 Rust tests passing) - -**CRG C requirements met:** -- [x] Unit tests present (120+ JS + 267 Rust) -- [x] Smoke tests (all Rust crates have at least smoke coverage) -- [x] Build verification (cargo test: 267/267 pass) -- [x] P2P property tests (tea_properties_test.mjs) -- [x] E2E tests (e2e_panel_lifecycle_test.js — 47 tests) -- [x] Reflexive tests (manifest_test.mjs) -- [x] Contract tests (panel_contracts_test.mjs) -- [x] Aspect tests (security_test.mjs) -- [x] Benchmarks baselined (benches/panll_bench.js + existing bench_test.js files) - -**Next grade (B):** Requires 686 ReScript modules to build + coverage measurement + 6 minimum A-tier targets. - -## FAKE-FUZZ ALERT - -- `tests/fuzz/placeholder.txt` is a scorecard placeholder inherited from rsr-template-repo — it does NOT provide real fuzz testing -- Replace with an actual fuzz harness (see rsr-template-repo/tests/fuzz/README.adoc) or remove the file -- Priority: P2 — creates false impression of fuzz coverage diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 59% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index dbc77030..fbe30b4d 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,24 +1,22 @@ - - - +== PanLL — Topology -# PanLL — Topology +=== Overview -## Overview +PanLL (pronounced "`parallel`") is a panel-based development environment +built on The Elm Architecture (TEA) in ReScript. It serves as a +cognitive-relief layer (eNSAID) — a Human-Things Interface (HTI) that +reduces friction, context-switching, and cognitive overhead during +development work. -PanLL (pronounced "parallel") is a panel-based development environment built on -The Elm Architecture (TEA) in ReScript. It serves as a cognitive-relief layer -(eNSAID) — a Human-Things Interface (HTI) that reduces friction, context-switching, -and cognitive overhead during development work. +The frontend is 686 ReScript source files organised into a strict TEA +decomposition: Model, Msg, Update, View, Commands, and Subscriptions. +The backend is a Gossamer shell (Zig + WebKitGTK) with 107 Rust modules +handling IPC, filesystem, and external service integration. 108 panels +are defined across 118 clade definitions. -The frontend is 686 ReScript source files organised into a strict TEA decomposition: -Model, Msg, Update, View, Commands, and Subscriptions. The backend is a Gossamer -shell (Zig + WebKitGTK) with 107 Rust modules handling IPC, filesystem, and -external service integration. 108 panels are defined across 118 clade definitions. +=== Module Structure -## Module Structure - -``` +.... src/ ├── App.res Entry point — mounts TEA application ├── Model.res State composition root (includes domain modules) @@ -117,11 +115,11 @@ src/ │ └── styles/ └── input.css Tailwind CSS input -``` +.... -### Backend (Gossamer — Rust) +==== Backend (Gossamer — Rust) -``` +.... src-gossamer/ ├── src/ [107] Rust backend modules │ ├── main.rs Gossamer application entry point @@ -142,100 +140,120 @@ src-gossamer/ │ ├── release_manager/ Release pipeline (5 commands) │ └── ... └── lib/ Shared Rust library code -``` +.... -### Clade Definitions +==== Clade Definitions -``` +.... panel-clades/ └── clades/ [118] A2ML clade definitions ├── core-*.a2ml Core panel clades ├── overlay-*.a2ml Overlay panel clades ├── gamedev-*.a2ml Game development panel clades (28) └── meta-*.a2ml Cross-cutting service clades -``` +.... -### Tests +==== Tests -``` +.... tests/ [137] Deno test files ├── tea_*.test.ts TEA runtime tests ├── engine_*.test.ts Engine unit tests (47 engines) ├── e2e_*.test.ts End-to-end panel lifecycle tests (40) ├── integration_*.test.ts Cross-panel integration tests └── bench_*.test.ts Performance benchmarks -``` +.... -## Architectural Decisions +=== Architectural Decisions -### TEA Framework (permanent) +==== TEA Framework (permanent) -PanLL uses a custom TEA (The Elm Architecture) runtime in `src/tea/` — 18 modules -with zero npm dependencies. All UI follows the cycle: +PanLL uses a custom TEA (The Elm Architecture) runtime in `+src/tea/+` — +18 modules with zero npm dependencies. All UI follows the cycle: -``` +.... Model -> Msg -> Update -> View -> (Cmd | Sub) -> ... -``` +.... -All state lives in `Model.model`. No global mutable state. No hooks, no Redux, -no MVC. The custom runtime includes VDOM diffing (`Tea_Render`), ARIA support -(`Tea_Vdom`), and animation frame subscriptions. +All state lives in `+Model.model+`. No global mutable state. No hooks, +no Redux, no MVC. The custom runtime includes VDOM diffing +(`+Tea_Render+`), ARIA support (`+Tea_Vdom+`), and animation frame +subscriptions. -### Gossamer Integration +==== Gossamer Integration -PanLL migrated from Tauri 2.0 to Gossamer (Zig + WebKitGTK). The Rust backend -in `src-gossamer/` provides IPC commands invoked from ReScript via -`src/core/RuntimeBridge.res`. The `GossamerEvents` subscription streams backend -events to the TEA message loop. +PanLL migrated from Tauri 2.0 to Gossamer (Zig + WebKitGTK). The Rust +backend in `+src-gossamer/+` provides IPC commands invoked from ReScript +via `+src/core/RuntimeBridge.res+`. The `+GossamerEvents+` subscription +streams backend events to the TEA message loop. -### VeriSimDB Backing +==== VeriSimDB Backing -Panel state, feedback history, and diagnostic data persist to VeriSimDB (port 8080) -via the `DatabaseModule` and `DatabaseBridgeEngine`. Queries use VCL-total through -the BoJ database-mcp cartridge when `bojRouting` is enabled. +Panel state, feedback history, and diagnostic data persist to VeriSimDB +(port 8080) via the `+DatabaseModule+` and `+DatabaseBridgeEngine+`. +Queries use VCL-total through the BoJ database-mcp cartridge when +`+bojRouting+` is enabled. -### Panel Organisation +==== Panel Organisation 108 panels are organised into categories: -| Category | Count | Description | -|----------|-------|-------------| -| Core panels | 3 | Panel-L (Symbolic), Panel-N (Neural), Panel-W (World) — always visible | -| General overlays | 14 | CloudGuard, VAB, Farm, Fleet, Hypatia, Reposystem, Aerie, Interfaces, Playgrounds, Plaza, Minter, Protocol-Squisher, My-Lang, BoJ | -| IDApTIK panels | 11 | Valence Shell, Game Preview, VM Inspector, Network Topology, Level Architect, Coprocessors, Multiplayer Monitor, DLC Workshop, Editor Bridge, Build Dashboard, Release Manager | -| Meta panels | 3 | Automation Router, Clade Browser, 7-Tentacles | -| Game dev panels | 28 | Clade definitions only (A2ML); ReScript implementation pending | -| Cross-cutting | 49 | TypeLL verification, A2ML/K9 integration, cognitive governance, provisioner | +[width="100%",cols="34%,23%,43%",options="header",] +|=== +|Category |Count |Description +|Core panels |3 |Panel-L (Symbolic), Panel-N (Neural), Panel-W (World) — +always visible + +|General overlays |14 |CloudGuard, VAB, Farm, Fleet, Hypatia, +Reposystem, Aerie, Interfaces, Playgrounds, Plaza, Minter, +Protocol-Squisher, My-Lang, BoJ + +|IDApTIK panels |11 |Valence Shell, Game Preview, VM Inspector, Network +Topology, Level Architect, Coprocessors, Multiplayer Monitor, DLC +Workshop, Editor Bridge, Build Dashboard, Release Manager + +|Meta panels |3 |Automation Router, Clade Browser, 7-Tentacles + +|Game dev panels |28 |Clade definitions only (A2ML); ReScript +implementation pending + +|Cross-cutting |49 |TypeLL verification, A2ML/K9 integration, cognitive +governance, provisioner +|=== -The three core panels form a permanent tiled layout. Overlay panels appear one -at a time on top of them, activated via the panel switcher bar. +The three core panels form a permanent tiled layout. Overlay panels +appear one at a time on top of them, activated via the panel switcher +bar. -### TypeLL Verification Kernel +==== TypeLL Verification Kernel -TypeLL provides cross-panel type intelligence. All 48 implemented panels are wired -to the verification kernel via `TypeCheckResult` messages. The `panelTypeChecks` -dictionary in the model tracks per-panel verification status. +TypeLL provides cross-panel type intelligence. All 48 implemented panels +are wired to the verification kernel via `+TypeCheckResult+` messages. +The `+panelTypeChecks+` dictionary in the model tracks per-panel +verification status. -### Cognitive Governance +==== Cognitive Governance Six always-present systems monitor operator state: -- **Vexometer** — friction index monitoring -- **Anti-Crash Gate** — neural token circuit breaker (all inference gated) -- **Orbital Drift Aura** — ambient stability indicator -- **Feedback-O-Tron** — BoJ-backed context persistence -- **Information Humidity** — UI density adaptation (High/Medium/Low) -- **Dark Start** — architecture manifold entry +* *Vexometer* — friction index monitoring +* *Anti-Crash Gate* — neural token circuit breaker (all inference gated) +* *Orbital Drift Aura* — ambient stability indicator +* *Feedback-O-Tron* — BoJ-backed context persistence +* *Information Humidity* — UI density adaptation (High/Medium/Low) +* *Dark Start* — architecture manifold entry -### Coprocessor Engine +==== Coprocessor Engine -Three-phase coprocessor routing: local CPU (when load < 80%), remote neural, -and BoJ fallback. The control plane (`src/core/CoprocessorsEngine.res`) manages -dispatch; the Zig FFI data plane handles computation. +Three-phase coprocessor routing: local CPU (when load < 80%), remote +neural, and BoJ fallback. The control plane +(`+src/core/CoprocessorsEngine.res+`) manages dispatch; the Zig FFI data +plane handles computation. -## Build and Test +=== Build and Test -```bash +[source,bash] +---- # Compile ReScript modules deno task res:build @@ -253,46 +271,64 @@ deno task test:coverage # ReScript watch mode deno task res:watch -``` - -## Integration Points - -| Service | Port | Protocol | Purpose | -|---------|------|----------|---------| -| Gossamer shell | — | IPC | Desktop webview host (Zig + WebKitGTK) | -| ECHIDNA | 9000 | HTTP | Theorem prover dispatch | -| VeriSimDB | 8080 | HTTP/VCL-total | 8-modality versioned database | -| BoJ-Server | 7700 | HTTP | Cartridge server (17 cartridges) and protocol gateway | -| TypeLL | 7800 | HTTP | Cross-panel type verification kernel | -| Hypatia | — | HTTP (Elixir) | Neurosymbolic CI/CD intelligence | -| gitbot-fleet | — | HTTP (Axum) | Bot orchestration (rhodibot, echidnabot, etc.) | -| Aerie | — | HTTP (V-lang) | Network analysis API | -| NQC proxy | 4000 | HTTP | Code execution sandbox | -| Groove | — | IPC/HTTP | Universal service discovery and capability negotiation | - -## File Counts (as of 2026-04-03) - -| Directory | .res files | .rs files | Description | -|-----------|-----------|-----------|-------------| -| `src/tea/` | 18 | — | Custom TEA runtime | -| `src/model/` | 117 | — | Domain model types | -| `src/msg/` | 117 | — | Message types | -| `src/update/` | 74 | — | Update functions | -| `src/core/` | 139 | — | Engine logic | -| `src/components/` | 123 | — | View components | -| `src/commands/` | 69 | — | Gossamer IPC commands | -| `src/modules/` | 19 | — | Registries and services | -| `src/subscriptions/` | 2 | — | TEA subscriptions | -| `src/*.res` | 7 | — | Top-level TEA wiring | -| `src-gossamer/` | — | 107 | Rust backend | -| **Total source** | **685** | **107** | **792 files** | -| `tests/` | — | — | 137 test files | -| `panel-clades/clades/` | — | — | 118 A2ML clade definitions | - -## See Also - -- `docs/architecture/TOPOLOGY.md` — detailed completion dashboard and cross-panel communication map -- `docs/architecture/PANEL-INVENTORY.md` — full catalog of all 108 panels -- `docs/architecture/ARCHITECTURE.md` — architectural narrative -- `docs/decisions/DESIGN-DECISIONS.md` — ADR log -- `docs/ENSAID.adoc` — eNSAID philosophy and design rationale +---- + +=== Integration Points + +[width="100%",cols="28%,17%,29%,26%",options="header",] +|=== +|Service |Port |Protocol |Purpose +|Gossamer shell |— |IPC |Desktop webview host (Zig + WebKitGTK) + +|ECHIDNA |9000 |HTTP |Theorem prover dispatch + +|VeriSimDB |8080 |HTTP/VCL-total |8-modality versioned database + +|BoJ-Server |7700 |HTTP |Cartridge server (17 cartridges) and protocol +gateway + +|TypeLL |7800 |HTTP |Cross-panel type verification kernel + +|Hypatia |— |HTTP (Elixir) |Neurosymbolic CI/CD intelligence + +|gitbot-fleet |— |HTTP (Axum) |Bot orchestration (rhodibot, echidnabot, +etc.) + +|Aerie |— |HTTP (V-lang) |Network analysis API + +|NQC proxy |4000 |HTTP |Code execution sandbox + +|Groove |— |IPC/HTTP |Universal service discovery and capability +negotiation +|=== + +=== File Counts (as of 2026-04-03) + +[cols=",,,",options="header",] +|=== +|Directory |.res files |.rs files |Description +|`+src/tea/+` |18 |— |Custom TEA runtime +|`+src/model/+` |117 |— |Domain model types +|`+src/msg/+` |117 |— |Message types +|`+src/update/+` |74 |— |Update functions +|`+src/core/+` |139 |— |Engine logic +|`+src/components/+` |123 |— |View components +|`+src/commands/+` |69 |— |Gossamer IPC commands +|`+src/modules/+` |19 |— |Registries and services +|`+src/subscriptions/+` |2 |— |TEA subscriptions +|`+src/*.res+` |7 |— |Top-level TEA wiring +|`+src-gossamer/+` |— |107 |Rust backend +|*Total source* |*685* |*107* |*792 files* +|`+tests/+` |— |— |137 test files +|`+panel-clades/clades/+` |— |— |118 A2ML clade definitions +|=== + +=== See Also + +* `+docs/architecture/TOPOLOGY.md+` — detailed completion dashboard and +cross-panel communication map +* `+docs/architecture/PANEL-INVENTORY.md+` — full catalog of all 108 +panels +* `+docs/architecture/ARCHITECTURE.md+` — architectural narrative +* `+docs/decisions/DESIGN-DECISIONS.md+` — ADR log +* `+docs/ENSAID.adoc+` — eNSAID philosophy and design rationale diff --git a/TRANSMUTABLE_PANEL_ARCHITECTURE.md b/TRANSMUTABLE_PANEL_ARCHITECTURE.adoc similarity index 63% rename from TRANSMUTABLE_PANEL_ARCHITECTURE.md rename to TRANSMUTABLE_PANEL_ARCHITECTURE.adoc index 4a341f6b..d4f82ee4 100644 --- a/TRANSMUTABLE_PANEL_ARCHITECTURE.md +++ b/TRANSMUTABLE_PANEL_ARCHITECTURE.adoc @@ -1,30 +1,34 @@ -# Transmutable Panel Architecture for Discipline Analyzers +== Transmutable Panel Architecture for Discipline Analyzers -> **HISTORICAL (2024, Mistral-Vibe era) — SUPERSEDED.** Kept for provenance; -> do not implement from this document. The groove dialect described here -> (port 9000, `groove_version` probing, capabilities-as-shown) predates the -> canonical protocol, and the five-mode "transmutation spectrum" was the -> precursor intuition of what is now the cleave dial. Current canon: -> the joinery naming ADR (groove `docs/decisions/0009`), groove -> `spec/SPEC.adoc` (v0.3: leases §4.6, signed manifests §2.1.5), -> `cleave/docs/KERNEL.adoc` + `RANKED-OWNERSHIP-CLEAVE.adoc` v0.3 (the -> dial, soft/hard as lease modes, posture TS-1..7), and -> `cleave/docs/architecture/THE-JOINERY.adoc` (orientation). +____ +*HISTORICAL (2024, Mistral-Vibe era) — SUPERSEDED.* Kept for provenance; +do not implement from this document. The groove dialect described here +(port 9000, `+groove_version+` probing, capabilities-as-shown) predates +the canonical protocol, and the five-mode "`transmutation spectrum`" was +the precursor intuition of what is now the cleave dial. Current canon: +the joinery naming ADR (groove `+docs/decisions/0009+`), groove +`+spec/SPEC.adoc+` (v0.3: leases §4.6, signed manifests §2.1.5), +`+cleave/docs/KERNEL.adoc+` + `+RANKED-OWNERSHIP-CLEAVE.adoc+` v0.3 (the +dial, soft/hard as lease modes, posture TS-1..7), and +`+cleave/docs/architecture/THE-JOINERY.adoc+` (orientation). +____ +*Date:* 2024-04-14 *Version:* 1.0 *Status:* Design Phase -**Date:** 2024-04-14 -**Version:** 1.0 -**Status:** Design Phase +=== Executive Summary -## Executive Summary +This document outlines the transmutable panel architecture for +Discipline Analyzers, designed to support multiple presentation modes +(standalone, CLI, TUI, eNSAID) while maintaining a unified core analysis +engine. This architecture leverages the +Minter/Provisioner/Configurator/Harness toolchain and integrates with +the Groove Protocol for service discovery. -This document outlines the transmutable panel architecture for Discipline Analyzers, designed to support multiple presentation modes (standalone, CLI, TUI, eNSAID) while maintaining a unified core analysis engine. This architecture leverages the Minter/Provisioner/Configurator/Harness toolchain and integrates with the Groove Protocol for service discovery. +=== Architecture Overview -## Architecture Overview +==== Transmutation Spectrum -### Transmutation Spectrum - -``` +.... ┌─────────────────────────────────────────────────────────────┐ │ TRANSMUTATION SPECTRUM │ ├────────────┬────────────┬────────────┬────────────┬────────────┤ @@ -34,11 +38,11 @@ This document outlines the transmutable panel architecture for Discipline Analyz ↑ ↑ ↑ ↑ Lightweight Scriptable Interactive Integrated Immersive (User Mode) (Automation) (Local) (Workflow) (Ambient) -``` +.... -### Core Components +==== Core Components -``` +.... ┌───────────────────────────────────────────────────────┐ │ Discipline Analyzers Core │ ├───────────────────┬───────────────────┬─────────────────┤ @@ -70,20 +74,19 @@ This document outlines the transmutable panel architecture for Discipline Analyz ┌─────────────────────┐ │ Presentation Layers │ └─────────────────────┘ -``` +.... + +=== Transmutation Modes -## Transmutation Modes +==== 1. Standalone Mode (Gossamer + Groove) -### 1. Standalone Mode (Gossamer + Groove) +*Characteristics:* - Lightweight, user-initiated - Groove-discoverable +service - Web-based interface - Minimal dependencies -**Characteristics:** -- Lightweight, user-initiated -- Groove-discoverable service -- Web-based interface -- Minimal dependencies +*Implementation:* -**Implementation:** -```julia +[source,julia] +---- # Standalone panel entry point function launch_standalone() # Start Groove server for discovery @@ -95,18 +98,17 @@ function launch_standalone() # Register with Gossamer register_gossamer_connector() end -``` +---- + +==== 2. CLI Mode (Scriptable Automation) -### 2. CLI Mode (Scriptable Automation) +*Characteristics:* - Headless operation - Scriptable analysis - +JSON/TOML output - CI/CD integration -**Characteristics:** -- Headless operation -- Scriptable analysis -- JSON/TOML output -- CI/CD integration +*Implementation:* -**Implementation:** -```julia +[source,julia] +---- # CLI interface function analyze_cli(args::Dict{String, Any}) # Parse CLI arguments @@ -123,18 +125,17 @@ function analyze_cli(args::Dict{String, Any}) # Output results in CLI format println(JSON.json(results, 2)) end -``` +---- -### 3. TUI Mode (Local Interactive) +==== 3. TUI Mode (Local Interactive) -**Characteristics:** -- Terminal-based UI -- Interactive analysis -- Local development -- Cursive/NCurses interface +*Characteristics:* - Terminal-based UI - Interactive analysis - Local +development - Cursive/NCurses interface -**Implementation:** -```julia +*Implementation:* + +[source,julia] +---- # TUI interface using Cursive function launch_tui() # Initialize Cursive session @@ -147,18 +148,17 @@ function launch_tui() # Start interactive session run(session) end -``` +---- + +==== 4. eNSAID Mode (PanLL Integration) -### 4. eNSAID Mode (PanLL Integration) +*Characteristics:* - Deep PanLL integration - Workflow-oriented - TSDM +work items - Octad storage -**Characteristics:** -- Deep PanLL integration -- Workflow-oriented -- TSDM work items -- Octad storage +*Implementation:* -**Implementation:** -```julia +[source,julia] +---- # PanLL clade definition [clade] id = "discipline-analyzers" @@ -180,18 +180,17 @@ engine = "src/panel/DisciplineEngine.res" view = "src/panel/DisciplineView.res" transmutable = true # Key transmutation flag modes = ["standalone", "cli", "tui", "ensaid"] -``` +---- -### 5. Deep Groove Mode (Ambient Integration) +==== 5. Deep Groove Mode (Ambient Integration) -**Characteristics:** -- Fully ambient -- Automatic discovery -- Context-aware +*Characteristics:* - Fully ambient - Automatic discovery - Context-aware - Persistent monitoring -**Implementation:** -```julia +*Implementation:* + +[source,julia] +---- # Deep Groove integration function integrate_deep_groove() # Register with ambient environment @@ -203,13 +202,14 @@ function integrate_deep_groove() # Enable context-aware analysis enable_context_awareness() end -``` +---- -## Transmutation Engine Design +=== Transmutation Engine Design -### Core Transmuter Module +==== Core Transmuter Module -```julia +[source,julia] +---- module Transmuter using JSON @@ -268,13 +268,14 @@ function apply_mode_settings(mode::Symbol, state::TransmutationState) end end # module -``` +---- -## Analysis Endpoints with Transmutation Support +=== Analysis Endpoints with Transmutation Support -### Unified Analysis API +==== Unified Analysis API -```julia +[source,julia] +---- """ Unified analysis endpoint that adapts to transmutation mode """ @@ -349,13 +350,14 @@ function analyze_ensaid(request::Dict{String, Any}) # Return PanLL-compatible format return format_for_panll(results, work_item) end -``` +---- -## Panel Implementation Strategy +=== Panel Implementation Strategy -### 1. Core Analysis Engine (Mode-Agnostic) +==== 1. Core Analysis Engine (Mode-Agnostic) -```julia +[source,julia] +---- module AnalysisEngine # Core analysis functions (work across all modes) @@ -389,11 +391,12 @@ function format_results(results::Dict, mode::Symbol) end end # module -``` +---- -### 2. Transmutable Panel Definition +==== 2. Transmutable Panel Definition -```a2ml +[source,a2ml] +---- # DisciplineAnalyzers.a2ml [clade] id = "discipline-analyzers" @@ -475,164 +478,171 @@ keyboard-navigable = true screen-reader-support = true aria-roles = ["dialog", "grid", "tab", "tablist"] transmutable-aria = true -``` - -## Implementation Roadmap - -### Phase 1: Core Transmutation Engine (Weeks 1-4) - -1. **Transmuter Module** - - [ ] Implement mode detection - - [ ] Create capability configuration - - [ ] Build mode-specific settings - - [ ] Add history tracking - -2. **Unified Analysis API** - - [ ] Design mode-agnostic core - - [ ] Implement mode-specific adapters - - [ ] Create result formatting system - - [ ] Add error handling - -3. **Basic Panel Structure** - - [ ] Create DisciplineModel.res - - [ ] Implement DisciplineEngine.res - - [ ] Design DisciplineTransmuter.res - - [ ] Test mode switching - -### Phase 2: Mode-Specific Implementations (Weeks 5-8) - -1. **Standalone Mode** - - [ ] Web interface (HTML/JS) - - [ ] Groove service integration - - [ ] Gossamer connector - - [ ] Visualization components - -2. **CLI Mode** - - [ ] Argument parsing - - [ ] JSON/TOML output - - [ ] Scriptable interface - - [ ] CI/CD integration - -3. **TUI Mode** - - [ ] Cursive/NCurses interface - - [ ] Interactive analysis - - [ ] Local session management - - [ ] Keyboard navigation - -4. **eNSAID Mode** - - [ ] PanLL clade registration - - [ ] TSDM work item integration - - [ ] Octad storage support - - [ ] Workflow integration - -### Phase 3: Deep Groove Integration (Weeks 9-12) - -1. **Ambient Monitoring** - - [ ] Runtime violation tracking - - [ ] Context-aware analysis - - [ ] Persistent monitoring - - [ ] Automatic discovery - -2. **Advanced Features** - - [ ] LLM-assisted analysis - - [ ] Formal verification integration - - [ ] Adaptive analysis levels - - [ ] Historical trend analysis - -3. **Ecosystem Integration** - - [ ] Hypatia security scanner - - [ ] Aerie workflow system - - [ ] Gossamer framework - - [ ] VeriSimDB storage - -## Technical Considerations - -### Transmutation Patterns - -1. **State Preservation** - - Maintain analysis state across mode switches - - Persist user preferences - - Preserve context between modes - -2. **Capability Mapping** - - CLI: Scriptable, headless, JSON output - - TUI: Interactive, local, terminal-based - - eNSAID: Workflow-integrated, TSDM-enabled - - Deep Groove: Ambient, persistent, context-aware - -3. **Performance Optimization** - - Lazy loading of mode-specific components - - Shared core analysis engine - - Minimal overhead for mode switching - - Efficient state serialization - -### Error Handling - -1. **Mode-Specific Errors** - - CLI: JSON-formatted error messages - - TUI: Interactive error resolution - - eNSAID: TSDM work item creation - - Deep Groove: Automatic recovery - -2. **Fallback Mechanisms** - - Graceful degradation between modes - - Automatic mode switching on failure - - User notification system - - Recovery procedures - -## Testing Strategy - -### Unit Tests -- Transmuter module functionality -- Mode switching logic -- Capability configuration -- State preservation - -### Integration Tests -- Groove service discovery -- PanLL clade registration -- TSDM work item creation -- Octad storage integration - -### End-to-End Tests -- Complete workflow in each mode -- Transmutation between modes -- Error handling scenarios -- Performance benchmarks - -### User Testing -- CLI usability testing -- TUI interaction testing -- eNSAID workflow testing -- Deep Groove ambient testing - -## Success Metrics - -### Quantitative -- **Mode Coverage:** 100% of planned modes implemented -- **Transmutation Time:** <100ms mode switching -- **Memory Overhead:** <10% per additional mode -- **Test Coverage:** 95%+ code coverage - -### Qualitative -- **User Experience:** Smooth transmutation between modes -- **Consistency:** Uniform behavior across modes -- **Flexibility:** Adaptable to different workflows -- **Reliability:** Robust error handling and recovery - -## Conclusion - -This transmutable panel architecture provides a comprehensive framework for implementing Discipline Analyzers with full support for multiple presentation modes. By leveraging the Minter/Provisioner/Configurator/Harness toolchain and integrating with the Groove Protocol, the system will provide both standalone functionality and deep eNSAID integration. - -The architecture respects the fundamental insight that panels are not fixed UI components but **transmutable entities** that can adapt to different contexts - from standalone tools to deeply integrated ambient components. This approach ensures maximum flexibility and user value across the entire development ecosystem. - -**Next Steps:** -1. Implement core transmuter module -2. Develop mode-agnostic analysis engine -3. Create basic panel structure -4. Test transmutation between modes - -**Maintainers:** @hyperpolymath/core-team -**Architect:** Mistral Vibe -**Target Completion:** 2024-06-14 -**Review Date:** 2024-05-14 (Phase 1 completion) \ No newline at end of file +---- + +=== Implementation Roadmap + +==== Phase 1: Core Transmutation Engine (Weeks 1-4) + +[arabic] +. *Transmuter Module* +* [ ] Implement mode detection +* [ ] Create capability configuration +* [ ] Build mode-specific settings +* [ ] Add history tracking +. *Unified Analysis API* +* [ ] Design mode-agnostic core +* [ ] Implement mode-specific adapters +* [ ] Create result formatting system +* [ ] Add error handling +. *Basic Panel Structure* +* [ ] Create DisciplineModel.res +* [ ] Implement DisciplineEngine.res +* [ ] Design DisciplineTransmuter.res +* [ ] Test mode switching + +==== Phase 2: Mode-Specific Implementations (Weeks 5-8) + +[arabic] +. *Standalone Mode* +* [ ] Web interface (HTML/JS) +* [ ] Groove service integration +* [ ] Gossamer connector +* [ ] Visualization components +. *CLI Mode* +* [ ] Argument parsing +* [ ] JSON/TOML output +* [ ] Scriptable interface +* [ ] CI/CD integration +. *TUI Mode* +* [ ] Cursive/NCurses interface +* [ ] Interactive analysis +* [ ] Local session management +* [ ] Keyboard navigation +. *eNSAID Mode* +* [ ] PanLL clade registration +* [ ] TSDM work item integration +* [ ] Octad storage support +* [ ] Workflow integration + +==== Phase 3: Deep Groove Integration (Weeks 9-12) + +[arabic] +. *Ambient Monitoring* +* [ ] Runtime violation tracking +* [ ] Context-aware analysis +* [ ] Persistent monitoring +* [ ] Automatic discovery +. *Advanced Features* +* [ ] LLM-assisted analysis +* [ ] Formal verification integration +* [ ] Adaptive analysis levels +* [ ] Historical trend analysis +. *Ecosystem Integration* +* [ ] Hypatia security scanner +* [ ] Aerie workflow system +* [ ] Gossamer framework +* [ ] VeriSimDB storage + +=== Technical Considerations + +==== Transmutation Patterns + +[arabic] +. *State Preservation* +* Maintain analysis state across mode switches +* Persist user preferences +* Preserve context between modes +. *Capability Mapping* +* CLI: Scriptable, headless, JSON output +* TUI: Interactive, local, terminal-based +* eNSAID: Workflow-integrated, TSDM-enabled +* Deep Groove: Ambient, persistent, context-aware +. *Performance Optimization* +* Lazy loading of mode-specific components +* Shared core analysis engine +* Minimal overhead for mode switching +* Efficient state serialization + +==== Error Handling + +[arabic] +. *Mode-Specific Errors* +* CLI: JSON-formatted error messages +* TUI: Interactive error resolution +* eNSAID: TSDM work item creation +* Deep Groove: Automatic recovery +. *Fallback Mechanisms* +* Graceful degradation between modes +* Automatic mode switching on failure +* User notification system +* Recovery procedures + +=== Testing Strategy + +==== Unit Tests + +* Transmuter module functionality +* Mode switching logic +* Capability configuration +* State preservation + +==== Integration Tests + +* Groove service discovery +* PanLL clade registration +* TSDM work item creation +* Octad storage integration + +==== End-to-End Tests + +* Complete workflow in each mode +* Transmutation between modes +* Error handling scenarios +* Performance benchmarks + +==== User Testing + +* CLI usability testing +* TUI interaction testing +* eNSAID workflow testing +* Deep Groove ambient testing + +=== Success Metrics + +==== Quantitative + +* *Mode Coverage:* 100% of planned modes implemented +* *Transmutation Time:* <100ms mode switching +* *Memory Overhead:* <10% per additional mode +* *Test Coverage:* 95%+ code coverage + +==== Qualitative + +* *User Experience:* Smooth transmutation between modes +* *Consistency:* Uniform behavior across modes +* *Flexibility:* Adaptable to different workflows +* *Reliability:* Robust error handling and recovery + +=== Conclusion + +This transmutable panel architecture provides a comprehensive framework +for implementing Discipline Analyzers with full support for multiple +presentation modes. By leveraging the +Minter/Provisioner/Configurator/Harness toolchain and integrating with +the Groove Protocol, the system will provide both standalone +functionality and deep eNSAID integration. + +The architecture respects the fundamental insight that panels are not +fixed UI components but *transmutable entities* that can adapt to +different contexts - from standalone tools to deeply integrated ambient +components. This approach ensures maximum flexibility and user value +across the entire development ecosystem. + +*Next Steps:* 1. Implement core transmuter module 2. Develop +mode-agnostic analysis engine 3. Create basic panel structure 4. Test +transmutation between modes + +*Maintainers:* @hyperpolymath/core-team *Architect:* Mistral Vibe +*Target Completion:* 2024-06-14 *Review Date:* 2024-05-14 (Phase 1 +completion) diff --git a/audits/audit-ffi-2026-05-26.adoc b/audits/audit-ffi-2026-05-26.adoc new file mode 100644 index 00000000..e1495b08 --- /dev/null +++ b/audits/audit-ffi-2026-05-26.adoc @@ -0,0 +1,35 @@ +== Audit: FFI / systems `+unsafe+` blocks (panll) + +*Auditor*: Jonathan D.A. Jewell *Date*: 2026-05-26 *Scope*: panic-attack +assail Critical/High `+UnsafeCode+` (PA001) and `+UnsafeFFI+` (PA007) +findings located under: `+ffi/zig/src/, src-gossamer/src/+`. +*Cross-reference*: campaign tracker +https://github.com/hyperpolymath/picpath/issues/32[hyperpolymath/panic-attack#32]. +*Registry*: `+audits/assail-classifications.a2ml+`. + +=== Rationale + +panll is a panel-clades language with a Tauri-style desktop wrapper. +ffi/zig/src is the Zig FFI bridge to the Idris2 core; src-gossamer/src +is the (frozen, see ADR-0001) Rust desktop shell using OS-FFI for +system_tray destroy, sysinfo workspace probing, and +coprocessor/llm_coding command pipes. All unsafe at the C-ABI / OS-FFI +boundary. + +The classification is scoped to the listed root(s). Any `+unsafe+` block +outside those roots remains visible to assail. + +=== Anti-gameability + +The registry is a separate file from any source under scan; adding a new +`+unsafe+` block inside a classified root requires a companion +classification edit and an update to this audit doc, both of which are +visible in the diff. + +=== Verification + +Locally on this branch: `+panic-attack assail . --headless+` reports the +listed PA001/PA007 findings as `+suppressed: true+`. Any new `+unsafe+` +outside the listed roots remains unsuppressed. + +Refs hyperpolymath/panic-attack#32. diff --git a/audits/audit-ffi-2026-05-26.md b/audits/audit-ffi-2026-05-26.md deleted file mode 100644 index 4d16b35b..00000000 --- a/audits/audit-ffi-2026-05-26.md +++ /dev/null @@ -1,28 +0,0 @@ - - -# Audit: FFI / systems `unsafe` blocks (panll) - -**Auditor**: Jonathan D.A. Jewell -**Date**: 2026-05-26 -**Scope**: panic-attack assail Critical/High `UnsafeCode` (PA001) and `UnsafeFFI` (PA007) findings located under: `ffi/zig/src/, src-gossamer/src/`. -**Cross-reference**: campaign tracker [hyperpolymath/panic-attack#32](https://github.com/hyperpolymath/picpath/issues/32). -**Registry**: `audits/assail-classifications.a2ml`. - -## Rationale - -panll is a panel-clades language with a Tauri-style desktop wrapper. ffi/zig/src is the Zig FFI bridge to the Idris2 core; src-gossamer/src is the (frozen, see ADR-0001) Rust desktop shell using OS-FFI for system_tray destroy, sysinfo workspace probing, and coprocessor/llm_coding command pipes. All unsafe at the C-ABI / OS-FFI boundary. - -The classification is scoped to the listed root(s). Any `unsafe` block outside those roots remains visible to assail. - -## Anti-gameability - -The registry is a separate file from any source under scan; adding a new `unsafe` block inside a classified root requires a companion classification edit and an update to this audit doc, both of which are visible in the diff. - -## Verification - -Locally on this branch: `panic-attack assail . --headless` reports the listed PA001/PA007 findings as `suppressed: true`. Any new `unsafe` outside the listed roots remains unsuppressed. - -Refs hyperpolymath/panic-attack#32. diff --git a/beam/panll_beam/README.adoc b/beam/panll_beam/README.adoc new file mode 100644 index 00000000..da4dfe45 --- /dev/null +++ b/beam/panll_beam/README.adoc @@ -0,0 +1,106 @@ +== PanllBeam + +BEAM runtime service for PanLL with selectable API frontdoors: + +* HTTP (Bandit + Plug) +* GraphQL (Absinthe + Bandit) +* gRPC (grpc-elixir + protobuf) + +All three can run together or be enabled selectively. + +=== API Modes + +Control enabled protocols with `+PANLL_BEAM_APIS+`: + +[source,bash] +---- +# Enable all protocols (default) +export PANLL_BEAM_APIS="http,graphql,grpc" + +# HTTP + gRPC only +export PANLL_BEAM_APIS="http,grpc" + +# GraphQL only +export PANLL_BEAM_APIS="graphql" +---- + +=== Ports + +[source,bash] +---- +# HTTP (default: 4100) +export PANLL_BEAM_HTTP_PORT=4100 + +# GraphQL (default: 4101) +export PANLL_BEAM_GRAPHQL_PORT=4101 + +# gRPC (default: 50051) +export PANLL_BEAM_GRPC_PORT=50051 + +# Backward compatible legacy HTTP port override +export PANLL_BEAM_PORT=4100 +---- + +=== Endpoints + +==== HTTP + +* `+GET /healthz+` +* `+GET /v1/status+` + +==== GraphQL + +* `+POST /graphql+` +* `+GET /graphiql+` +* `+GET /healthz+` + +GraphQL query example: + +[source,graphql] +---- +query { + health + status { + service + status + runtime + version + apis + } +} +---- + +==== gRPC + +Service: `+panll.v1.StatusService+` + +* `+GetStatus(StatusRequest) returns (StatusReply)+` + +=== Run + +[source,bash] +---- +mix deps.get +mix test +mix run --no-halt +---- + +=== Installation + +If https://hex.pm/docs/publish[available in Hex], the package can be +installed by adding `+panll_beam+` to your list of dependencies in +`+mix.exs+`: + +[source,elixir] +---- +def deps do + [ + {:panll_beam, "~> 0.1.0"} + ] +end +---- + +Documentation can be generated with +https://github.com/elixir-lang/ex_doc[ExDoc] and published on +https://hexdocs.pm[HexDocs]. Once published, the docs can be found at +https://hexdocs.pm/panll_beam. diff --git a/beam/panll_beam/README.md b/beam/panll_beam/README.md deleted file mode 100644 index 89d5289d..00000000 --- a/beam/panll_beam/README.md +++ /dev/null @@ -1,99 +0,0 @@ -# PanllBeam - -BEAM runtime service for PanLL with selectable API frontdoors: - -- HTTP (Bandit + Plug) -- GraphQL (Absinthe + Bandit) -- gRPC (grpc-elixir + protobuf) - -All three can run together or be enabled selectively. - -## API Modes - -Control enabled protocols with `PANLL_BEAM_APIS`: - -```bash -# Enable all protocols (default) -export PANLL_BEAM_APIS="http,graphql,grpc" - -# HTTP + gRPC only -export PANLL_BEAM_APIS="http,grpc" - -# GraphQL only -export PANLL_BEAM_APIS="graphql" -``` - -## Ports - -```bash -# HTTP (default: 4100) -export PANLL_BEAM_HTTP_PORT=4100 - -# GraphQL (default: 4101) -export PANLL_BEAM_GRAPHQL_PORT=4101 - -# gRPC (default: 50051) -export PANLL_BEAM_GRPC_PORT=50051 - -# Backward compatible legacy HTTP port override -export PANLL_BEAM_PORT=4100 -``` - -## Endpoints - -### HTTP - -- `GET /healthz` -- `GET /v1/status` - -### GraphQL - -- `POST /graphql` -- `GET /graphiql` -- `GET /healthz` - -GraphQL query example: - -```graphql -query { - health - status { - service - status - runtime - version - apis - } -} -``` - -### gRPC - -Service: `panll.v1.StatusService` - -- `GetStatus(StatusRequest) returns (StatusReply)` - -## Run - -```bash -mix deps.get -mix test -mix run --no-halt -``` - -## Installation - -If [available in Hex](https://hex.pm/docs/publish), the package can be installed -by adding `panll_beam` to your list of dependencies in `mix.exs`: - -```elixir -def deps do - [ - {:panll_beam, "~> 0.1.0"} - ] -end -``` - -Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc) -and published on [HexDocs](https://hexdocs.pm). Once published, the docs can -be found at . diff --git a/blog/v0.2.0-release.adoc b/blog/v0.2.0-release.adoc new file mode 100644 index 00000000..52c3f261 --- /dev/null +++ b/blog/v0.2.0-release.adoc @@ -0,0 +1,234 @@ +== PanLL v0.2.0 "`Connected Workbench`" Released! + +*May 15, 2024* — We’re thrilled to announce the release of PanLL v0.2.0 +"`Connected Workbench`", a major milestone that transforms PanLL from a +personal productivity tool into a collaborative workbench for teams and +power users. + +=== 🚀 What’s New in v0.2.0 + +==== 1. *Identity Management System* 🆕 + +The centerpiece of v0.2.0 is our new *Identity Management System*, which +allows you to capture, save, load, and share complete workbench +configurations. + +*Key Features*: - *Snapshots*: Save your entire panel layout, settings, +and service configurations - *Team Broadcasting*: Share configurations +with teammates via Burble - *VeriSimDB Integration*: Primary storage +with automatic filesystem fallback - *Versioning*: Track changes over +time with snapshot history + +[source,bash] +---- +# Save your current setup +panll identity save --name "Project X Setup" + +# Load a previous configuration +panll identity load + +# Broadcast to your team +panll team broadcast +---- + +==== 2. *Gossamer Backend* 🔧 + +We’ve replaced the Tauri backend with *Gossamer*, our custom webview +shell written in Zig and Rust. This provides: + +* *Better Performance*: 30-50% faster startup and lower memory usage +* *Native Integration*: Tighter system integration with proper tray +support +* *Simplified FFI*: Cleaner foreign function interface for Rust +extensions +* *Smaller Footprint*: Reduced binary size by ~40% + +==== 3. *Enhanced System Tray* 📋 + +The system tray has been completely redesigned with new capabilities: + +* *Service Management*: Toggle Burble/Gossamer services directly from +the tray +* *Quick Actions*: One-click access to common tasks +* *Status Monitoring*: Real-time service health indicators +* *Notifications*: Alerts for team broadcasts and important events + +==== 4. *Burble Integration* 🌐 + +v0.2.0 introduces deep integration with +https://github.com/hyperpolymath/burble[Burble], our team coordination +service: + +* *Real-time Broadcasting*: Share identity snapshots instantly +* *Presence Awareness*: See who’s online and available +* *Team Synchronization*: Keep configurations in sync across your team +* *Broadcast History*: Track what’s been shared and when + +==== 5. *Performance Optimizations* ⚡ + +Under the hood, we’ve made significant performance improvements: + +* *Caching Layer*: LRU cache for identity operations (85%+ hit rate) +* *Batch Processing*: Parallel operations for bulk tasks +* *Compression*: Automatic compression for large snapshots (>5x ratio) +* *Connection Pooling*: Reused database connections + +*Performance Gains*: - Identity save: *<50ms* (was ~150ms) - Identity +load: *<60ms* (was ~200ms) - Team broadcast: *<100ms* (was ~300ms) + +=== 🎯 Migration Guide + +Upgrading from v0.1.x? We’ve made the transition as smooth as possible: + +[source,bash] +---- +# Backup your existing installation +panll-migration-backup.sh + +# Install v0.2.0 +wget https://github.com/hyperpolymath/panll/releases/download/v0.2.0/panll-v0.2.0-linux-x86_64.tar.gz +tar -xzf panll-v0.2.0-linux-x86_64.tar.gz +cd panll-v0.2.0-linux-x86_64 +sudo ./install.sh + +# Migrate your data +panll-migrate-config.sh +panll-migrate-data.sh + +# Start the new version +systemctl start panll +---- + +*Full Migration Guide*: https://panll.hyperpolymath.dev/docs/migration + +=== 📊 By The Numbers + +* *Lines of Code*: 42,387 (+18% from v0.1.x) +* *Tests*: 109 passing (97 JS + 12 Rust) +* *Documentation*: 84.8KB of comprehensive guides +* *Commands*: 270 backend commands registered +* *Panels*: 106 defined in the panel registry + +=== 🔧 Under the Hood + +==== Architecture Changes + +[source,mermaid] +---- +graph TD + A[Frontend: ReScript] -->|Gossamer FFI| B[Backend: Rust] + B -->|HTTP| C[VeriSimDB] + B -->|HTTP| D[Burble] + B -->|FS| E[Local Storage] + C -->|SQLite| F[Database] + D -->|WebSocket| G[Team Members] +---- + +==== Technology Stack + +[cols=",,",options="header",] +|=== +|Component |Technology |Purpose +|*Frontend* |ReScript/React |User interface +|*Backend* |Rust |Business logic +|*Shell* |Gossamer (Zig) |Native integration +|*Storage* |VeriSimDB (Rust) |Primary storage +|*Messaging* |Burble (Rust) |Team coordination +|*Testing* |Deno + Rust |Quality assurance +|=== + +=== 📚 Documentation + +We’ve completely overhauled our documentation for v0.2.0: + +* *https://panll.hyperpolymath.dev/docs/admin-guide[Admin Guide]*: +Deployment and configuration +* *https://panll.hyperpolymath.dev/docs/developer-guide[Developer +Guide]*: Extending PanLL +* *https://panll.hyperpolymath.dev/docs/migration[Migration Guide]*: +Upgrading from v0.1.x +* *https://panll.hyperpolymath.dev/docs/identity-user-guide[User +Guide]*: Using identity management +* *https://panll.hyperpolymath.dev/docs/api-reference[API Reference]*: +Complete API documentation + +=== 🤝 Community + +==== Get Involved + +* *GitHub*: https://github.com/hyperpolymath/panll +* *Discussions*: https://github.com/hyperpolymath/panll/discussions +* *Issues*: https://github.com/hyperpolymath/panll/issues +* *Email*: support@hyperpolymath.dev + +==== Contributing + +We welcome contributions! Check out our +https://panll.hyperpolymath.dev/docs/developer-guide#contributing-to-core[Contribution +Guidelines] to get started. + +==== Roadmap + +v0.2.0 is just the beginning. Here’s what’s coming next: + +*v0.2.1* (June 2024): - Snapshot diffing tool - Tagging system for +identities - Performance caching layer - Batch operations API + +*v0.3.0* (Q3 2024): - Ambient integration - Real-time collaboration - +Shared workspaces - Presence system + +=== 🎉 Try It Out + +==== Download + +*Linux x86_64*: +https://github.com/hyperpolymath/panll/releases/download/v0.2.0/panll-v0.2.0-linux-x86_64.tar.gz[panll-v0.2.0-linux-x86_64.tar.gz] + +*Source Code*: https://github.com/hyperpolymath/panll + +==== Quick Start + +[source,bash] +---- +# Install +wget https://github.com/hyperpolymath/panll/releases/download/v0.2.0/panll-v0.2.0-linux-x86_64.tar.gz +tar -xzf panll-v0.2.0-linux-x86_64.tar.gz +cd panll-v0.2.0-linux-x86_64 +sudo ./install.sh + +# Start services +sudo systemctl start verisimdb +sudo systemctl start burble +sudo systemctl start panll + +# Open in browser +xdg-open http://localhost:8080/public/ +---- + +=== 🙏 Acknowledgments + +v0.2.0 represents thousands of hours of work from our incredible +community: + +* *Core Team*: Jonathan D.A. Jewell, Claude, Vibe, Gemini +* *Contributors*: 42 individuals who submitted code, documentation, and +bug reports +* *Testers*: 89 beta testers who provided invaluable feedback +* *Sponsors*: Our generous sponsors who make this possible + +=== 📰 What’s Next? + +Stay tuned for our upcoming *Community Workshop* on June 5th, where +we’ll dive deep into v0.2.0’s features and show you how to get the most +out of PanLL’s new capabilities. + +*Register Now*: https://panll.hyperpolymath.dev/workshop + +''''' + +*PanLL v0.2.0* — Building the future of ambient computing, one panel at +a time. + +https://github.com/hyperpolymath/panll/releases/tag/v0.2.0[Download Now] +| https://panll.hyperpolymath.dev/docs[Documentation] | +https://github.com/hyperpolymath/panll/discussions[Community] diff --git a/blog/v0.2.0-release.md b/blog/v0.2.0-release.md deleted file mode 100644 index 444e0f30..00000000 --- a/blog/v0.2.0-release.md +++ /dev/null @@ -1,210 +0,0 @@ -# PanLL v0.2.0 "Connected Workbench" Released! - -**May 15, 2024** — We're thrilled to announce the release of PanLL v0.2.0 "Connected Workbench", a major milestone that transforms PanLL from a personal productivity tool into a collaborative workbench for teams and power users. - -## 🚀 What's New in v0.2.0 - -### 1. **Identity Management System** 🆕 - -The centerpiece of v0.2.0 is our new **Identity Management System**, which allows you to capture, save, load, and share complete workbench configurations. - -**Key Features**: -- **Snapshots**: Save your entire panel layout, settings, and service configurations -- **Team Broadcasting**: Share configurations with teammates via Burble -- **VeriSimDB Integration**: Primary storage with automatic filesystem fallback -- **Versioning**: Track changes over time with snapshot history - -```bash -# Save your current setup -panll identity save --name "Project X Setup" - -# Load a previous configuration -panll identity load - -# Broadcast to your team -panll team broadcast -``` - -### 2. **Gossamer Backend** 🔧 - -We've replaced the Tauri backend with **Gossamer**, our custom webview shell written in Zig and Rust. This provides: - -- **Better Performance**: 30-50% faster startup and lower memory usage -- **Native Integration**: Tighter system integration with proper tray support -- **Simplified FFI**: Cleaner foreign function interface for Rust extensions -- **Smaller Footprint**: Reduced binary size by ~40% - -### 3. **Enhanced System Tray** 📋 - -The system tray has been completely redesigned with new capabilities: - -- **Service Management**: Toggle Burble/Gossamer services directly from the tray -- **Quick Actions**: One-click access to common tasks -- **Status Monitoring**: Real-time service health indicators -- **Notifications**: Alerts for team broadcasts and important events - -### 4. **Burble Integration** 🌐 - -v0.2.0 introduces deep integration with [Burble](https://github.com/hyperpolymath/burble), our team coordination service: - -- **Real-time Broadcasting**: Share identity snapshots instantly -- **Presence Awareness**: See who's online and available -- **Team Synchronization**: Keep configurations in sync across your team -- **Broadcast History**: Track what's been shared and when - -### 5. **Performance Optimizations** ⚡ - -Under the hood, we've made significant performance improvements: - -- **Caching Layer**: LRU cache for identity operations (85%+ hit rate) -- **Batch Processing**: Parallel operations for bulk tasks -- **Compression**: Automatic compression for large snapshots (>5x ratio) -- **Connection Pooling**: Reused database connections - -**Performance Gains**: -- Identity save: **<50ms** (was ~150ms) -- Identity load: **<60ms** (was ~200ms) -- Team broadcast: **<100ms** (was ~300ms) - -## 🎯 Migration Guide - -Upgrading from v0.1.x? We've made the transition as smooth as possible: - -```bash -# Backup your existing installation -panll-migration-backup.sh - -# Install v0.2.0 -wget https://github.com/hyperpolymath/panll/releases/download/v0.2.0/panll-v0.2.0-linux-x86_64.tar.gz -tar -xzf panll-v0.2.0-linux-x86_64.tar.gz -cd panll-v0.2.0-linux-x86_64 -sudo ./install.sh - -# Migrate your data -panll-migrate-config.sh -panll-migrate-data.sh - -# Start the new version -systemctl start panll -``` - -**Full Migration Guide**: [https://panll.hyperpolymath.dev/docs/migration](https://panll.hyperpolymath.dev/docs/migration) - -## 📊 By The Numbers - -- **Lines of Code**: 42,387 (+18% from v0.1.x) -- **Tests**: 109 passing (97 JS + 12 Rust) -- **Documentation**: 84.8KB of comprehensive guides -- **Commands**: 270 backend commands registered -- **Panels**: 106 defined in the panel registry - -## 🔧 Under the Hood - -### Architecture Changes - -```mermaid -graph TD - A[Frontend: ReScript] -->|Gossamer FFI| B[Backend: Rust] - B -->|HTTP| C[VeriSimDB] - B -->|HTTP| D[Burble] - B -->|FS| E[Local Storage] - C -->|SQLite| F[Database] - D -->|WebSocket| G[Team Members] -``` - -### Technology Stack - -| Component | Technology | Purpose | -|-----------|------------|---------| -| **Frontend** | ReScript/React | User interface | -| **Backend** | Rust | Business logic | -| **Shell** | Gossamer (Zig) | Native integration | -| **Storage** | VeriSimDB (Rust) | Primary storage | -| **Messaging** | Burble (Rust) | Team coordination | -| **Testing** | Deno + Rust | Quality assurance | - -## 📚 Documentation - -We've completely overhauled our documentation for v0.2.0: - -- **[Admin Guide](https://panll.hyperpolymath.dev/docs/admin-guide)**: Deployment and configuration -- **[Developer Guide](https://panll.hyperpolymath.dev/docs/developer-guide)**: Extending PanLL -- **[Migration Guide](https://panll.hyperpolymath.dev/docs/migration)**: Upgrading from v0.1.x -- **[User Guide](https://panll.hyperpolymath.dev/docs/identity-user-guide)**: Using identity management -- **[API Reference](https://panll.hyperpolymath.dev/docs/api-reference)**: Complete API documentation - -## 🤝 Community - -### Get Involved - -- **GitHub**: [https://github.com/hyperpolymath/panll](https://github.com/hyperpolymath/panll) -- **Discussions**: [https://github.com/hyperpolymath/panll/discussions](https://github.com/hyperpolymath/panll/discussions) -- **Issues**: [https://github.com/hyperpolymath/panll/issues](https://github.com/hyperpolymath/panll/issues) -- **Email**: support@hyperpolymath.dev - -### Contributing - -We welcome contributions! Check out our [Contribution Guidelines](https://panll.hyperpolymath.dev/docs/developer-guide#contributing-to-core) to get started. - -### Roadmap - -v0.2.0 is just the beginning. Here's what's coming next: - -**v0.2.1** (June 2024): -- Snapshot diffing tool -- Tagging system for identities -- Performance caching layer -- Batch operations API - -**v0.3.0** (Q3 2024): -- Ambient integration -- Real-time collaboration -- Shared workspaces -- Presence system - -## 🎉 Try It Out - -### Download - -**Linux x86_64**: [panll-v0.2.0-linux-x86_64.tar.gz](https://github.com/hyperpolymath/panll/releases/download/v0.2.0/panll-v0.2.0-linux-x86_64.tar.gz) - -**Source Code**: [https://github.com/hyperpolymath/panll](https://github.com/hyperpolymath/panll) - -### Quick Start - -```bash -# Install -wget https://github.com/hyperpolymath/panll/releases/download/v0.2.0/panll-v0.2.0-linux-x86_64.tar.gz -tar -xzf panll-v0.2.0-linux-x86_64.tar.gz -cd panll-v0.2.0-linux-x86_64 -sudo ./install.sh - -# Start services -sudo systemctl start verisimdb -sudo systemctl start burble -sudo systemctl start panll - -# Open in browser -xdg-open http://localhost:8080/public/ -``` - -## 🙏 Acknowledgments - -v0.2.0 represents thousands of hours of work from our incredible community: - -- **Core Team**: Jonathan D.A. Jewell, Claude, Vibe, Gemini -- **Contributors**: 42 individuals who submitted code, documentation, and bug reports -- **Testers**: 89 beta testers who provided invaluable feedback -- **Sponsors**: Our generous sponsors who make this possible - -## 📰 What's Next? - -Stay tuned for our upcoming **Community Workshop** on June 5th, where we'll dive deep into v0.2.0's features and show you how to get the most out of PanLL's new capabilities. - -**Register Now**: [https://panll.hyperpolymath.dev/workshop](https://panll.hyperpolymath.dev/workshop) - ---- - -**PanLL v0.2.0** — Building the future of ambient computing, one panel at a time. - -[Download Now](https://github.com/hyperpolymath/panll/releases/tag/v0.2.0) | [Documentation](https://panll.hyperpolymath.dev/docs) | [Community](https://github.com/hyperpolymath/panll/discussions) \ No newline at end of file diff --git a/docs/ACCESSIBILITY-AUDIT-2026-03-29.adoc b/docs/ACCESSIBILITY-AUDIT-2026-03-29.adoc new file mode 100644 index 00000000..d139a769 --- /dev/null +++ b/docs/ACCESSIBILITY-AUDIT-2026-03-29.adoc @@ -0,0 +1,106 @@ +== PanLL Accessibility Audit + +*Date:* 2026-03-29 *Auditor:* Claude (automated scan) — manual testing +with NVDA/Orca still needed *Scope:* All 123 component files in +src/components/, supporting engines, tests + +=== Summary + +[cols=",,",options="header",] +|=== +|Metric |Count |Rating +|Components with ariaLabel |91/123 |Good (74%) +|Components with role attributes |90/123 |Good (73%) +|Components with keyboard handlers |1/123 |Critical gap +|Components with tabIndex |2/123 |Critical gap +|aria-live regions |7 total |Poor +|sr-only screen reader text |1 (skip-links only) |Poor +|ariaDescribedBy / ariaLabelledBy |8 total |Poor +|Colour palettes defined |4 |Complete +|Font size presets |4 (14-20px) |Complete +|Focus style options |4 |Complete +|Accessibility engine tests |30+ |Complete +|=== + +=== Architecture (Excellent) + +PanLL has dedicated accessibility infrastructure: - +`+AccessibilityEngine.res+` — theme, palette, animation, font, focus - +`+AccessibilityModel.res+` — type-safe state - +`+AccessibilityToolbar.res+` — floating FAB widget - +`+FocusDimmingEngine.res+` — focus indicator styling - +`+KeyboardUtil.res+` — keyboard utilities - +`+accessibility-baseline.k9.ncl+` — K9 validator contract + +=== Critical Gaps + +==== 1. Keyboard Navigation (Priority 1) + +Only 1 of 123 components (MyLang.res) has keyboard event handlers. All +interactive panels need: - Enter/Space to activate buttons - Arrow keys +for lists/tabs - Escape to close overlays + +*Remediation:* Add a `+KeyboardNav.res+` utility module with standard +handlers that components can compose. Target: all 108 panels +keyboard-navigable. + +==== 2. Tab Order (Priority 1) + +Only 2 components use tabIndex. Custom interactive elements are +invisible to keyboard users. + +*Remediation:* Add `+Attrs.tabIndex(0)+` to all custom interactive +elements. Add `+Attrs.tabIndex(-1)+` to programmatically focusable +containers. + +==== 3. Live Regions (Priority 2) + +Only 7 aria-live regions across 108+ panels. Status changes, form +validation, and dynamic content updates are silent to screen readers. + +*Remediation:* Add `+aria-live="polite"+` to status bars, notification +areas, and VCL result displays. Add `+aria-live="assertive"+` to error +messages. + +==== 4. Screen Reader Text (Priority 2) + +Only 1 sr-only instance (skip-links). Icon-only buttons, data +visualizations, and status indicators lack text alternatives. + +*Remediation:* Add sr-only labels to icon buttons and decorative +elements that carry meaning. + +==== 5. Complex Relationships (Priority 3) + +Only 8 ariaDescribedBy/ariaLabelledBy instances. Form fields, error +messages, and complex controls need semantic linking. + +=== What’s Already Working + +* 4 colour palettes (Standard, Deuteranopia, Protanopia, High Contrast) +* Scalable font sizes (14-20px presets, rem-based) +* Reduced motion detection and respect +* Focus indicator options (Default, High Contrast, Thick, Dotted) +* OS theme preference detection (System mode) +* Floating accessibility toolbar (non-intrusive FAB) +* 30+ engine-level tests for preference persistence + +=== DD-008 Compliance + +[cols=",,",options="header",] +|=== +|Level |Criteria |Status +|Baseline |ariaLabel + role per component |90/123 (73%) +|Full |Baseline + keyboard + tabIndex |~3/123 (~2%) +|Target |Full + aria-live + sr-only |0% +|=== + +=== Next Steps + +[arabic] +. Create `+KeyboardNav.res+` utility with composable keyboard handlers +. Add tabIndex to all custom interactive elements +. Add aria-live regions to status-changing areas +. Add sr-only labels to icon-only buttons +. Manual testing with NVDA/Orca (requires Jonathan) +. Update K9 validator to enforce full compliance diff --git a/docs/ACCESSIBILITY-AUDIT-2026-03-29.md b/docs/ACCESSIBILITY-AUDIT-2026-03-29.md deleted file mode 100644 index 83b6b9ba..00000000 --- a/docs/ACCESSIBILITY-AUDIT-2026-03-29.md +++ /dev/null @@ -1,103 +0,0 @@ - - - -# PanLL Accessibility Audit - -**Date:** 2026-03-29 -**Auditor:** Claude (automated scan) — manual testing with NVDA/Orca still needed -**Scope:** All 123 component files in src/components/, supporting engines, tests - -## Summary - -| Metric | Count | Rating | -|--------|-------|--------| -| Components with ariaLabel | 91/123 | Good (74%) | -| Components with role attributes | 90/123 | Good (73%) | -| Components with keyboard handlers | 1/123 | Critical gap | -| Components with tabIndex | 2/123 | Critical gap | -| aria-live regions | 7 total | Poor | -| sr-only screen reader text | 1 (skip-links only) | Poor | -| ariaDescribedBy / ariaLabelledBy | 8 total | Poor | -| Colour palettes defined | 4 | Complete | -| Font size presets | 4 (14-20px) | Complete | -| Focus style options | 4 | Complete | -| Accessibility engine tests | 30+ | Complete | - -## Architecture (Excellent) - -PanLL has dedicated accessibility infrastructure: -- `AccessibilityEngine.res` — theme, palette, animation, font, focus -- `AccessibilityModel.res` — type-safe state -- `AccessibilityToolbar.res` — floating FAB widget -- `FocusDimmingEngine.res` — focus indicator styling -- `KeyboardUtil.res` — keyboard utilities -- `accessibility-baseline.k9.ncl` — K9 validator contract - -## Critical Gaps - -### 1. Keyboard Navigation (Priority 1) - -Only 1 of 123 components (MyLang.res) has keyboard event handlers. -All interactive panels need: -- Enter/Space to activate buttons -- Arrow keys for lists/tabs -- Escape to close overlays - -**Remediation:** Add a `KeyboardNav.res` utility module with standard handlers -that components can compose. Target: all 108 panels keyboard-navigable. - -### 2. Tab Order (Priority 1) - -Only 2 components use tabIndex. Custom interactive elements are invisible -to keyboard users. - -**Remediation:** Add `Attrs.tabIndex(0)` to all custom interactive elements. -Add `Attrs.tabIndex(-1)` to programmatically focusable containers. - -### 3. Live Regions (Priority 2) - -Only 7 aria-live regions across 108+ panels. Status changes, form validation, -and dynamic content updates are silent to screen readers. - -**Remediation:** Add `aria-live="polite"` to status bars, notification areas, -and VCL result displays. Add `aria-live="assertive"` to error messages. - -### 4. Screen Reader Text (Priority 2) - -Only 1 sr-only instance (skip-links). Icon-only buttons, data visualizations, -and status indicators lack text alternatives. - -**Remediation:** Add sr-only labels to icon buttons and decorative elements -that carry meaning. - -### 5. Complex Relationships (Priority 3) - -Only 8 ariaDescribedBy/ariaLabelledBy instances. Form fields, error messages, -and complex controls need semantic linking. - -## What's Already Working - -- 4 colour palettes (Standard, Deuteranopia, Protanopia, High Contrast) -- Scalable font sizes (14-20px presets, rem-based) -- Reduced motion detection and respect -- Focus indicator options (Default, High Contrast, Thick, Dotted) -- OS theme preference detection (System mode) -- Floating accessibility toolbar (non-intrusive FAB) -- 30+ engine-level tests for preference persistence - -## DD-008 Compliance - -| Level | Criteria | Status | -|-------|----------|--------| -| Baseline | ariaLabel + role per component | 90/123 (73%) | -| Full | Baseline + keyboard + tabIndex | ~3/123 (~2%) | -| Target | Full + aria-live + sr-only | 0% | - -## Next Steps - -1. Create `KeyboardNav.res` utility with composable keyboard handlers -2. Add tabIndex to all custom interactive elements -3. Add aria-live regions to status-changing areas -4. Add sr-only labels to icon-only buttons -5. Manual testing with NVDA/Orca (requires Jonathan) -6. Update K9 validator to enforce full compliance diff --git a/docs/CRG-DOGFOOD-CHECKLIST.adoc b/docs/CRG-DOGFOOD-CHECKLIST.adoc new file mode 100644 index 00000000..afd85cb8 --- /dev/null +++ b/docs/CRG-DOGFOOD-CHECKLIST.adoc @@ -0,0 +1,91 @@ +== CRG D→C Dogfooding Checklist + +=== What Grade C Means + +Grade C (Beta) requires *real backend connections* and *author +dogfooding*. This cannot be automated — it requires Jonathan using PanLL +for actual work. + +=== Prerequisites (Must Be True Before Dogfooding) + +* [x] All 108 panels compile (0 errors, 0 warnings) +* [x] 2462+ tests passing +* [x] Zero dangerous patterns in source (Obj.magic, believe_me, etc.) +* [x] Gossamer backend builds (`+cargo check+` clean) +* [x] Dev server starts (`+deno task dev+`) +* [ ] VeriSimDB running on port 8093 +* [ ] BoJ-server running on port 7700 (SSE on 7703) +* [ ] ECHIDNA available on port 9000 + +=== Backend Connection Verification (Minimum 4 of 9) + +Each backend must return real data, not mock JSON. + +[width="100%",cols="10%,25%,16%,27%,22%",options="header",] +|=== +|# |Backend |Port |Panel(s) |Status +|1 |BoJ-server |7700 |BoJ Panel, Automation Router |☐ + +|2 |VeriSimDB |8093 |Panel-W, VCL Panel |☐ + +|3 |ECHIDNA |9000 |Panel-N, Proofs Bridge |☐ + +|4 |gitbot-fleet |8080 |Gitbot-Fleet Panel |☐ + +|5 |Hypatia |(Elixir) |Hypatia Panel |☐ + +|6 |Git blame |(local) |Provenance Map |✓ code verified (2026-03-29) — +provenance/commands.rs wired + +|7 |Filesystem |(local) |Farm, Watcher |✓ code verified (2026-03-29) — +farm/commands.rs + watcher/commands.rs wired + +|8 |TypeLL |7800 |Cross-panel type checking |☐ + +|9 |Stapeln |(local) |Container management |☐ +|=== + +=== Dogfooding Sessions (Minimum 3) + +Each session must be logged with date, duration, what was done, and +issues found. + +[cols=",,,,,",options="header",] +|=== +|# |Date |Duration |What Was Done |Issues Found |Panels Promoted +|1 | | | | | +|2 | | | | | +|3 | | | | | +|=== + +=== Per-Panel C-Grade Criteria + +A panel earns CRG C when ALL of these are true: + +[arabic] +. *Live data*: At least one backend returns real (not mock) data +. *End-to-end*: User action → backend call → result displayed (full +cycle) +. *Error handling*: Network failures show meaningful error, not crash +. *Keyboard nav*: All interactive elements reachable via Tab/Enter +. *No stale state*: Panel reflects current backend state on refresh + +=== Promotion Candidates (Easiest to Promote First) + +These panels have the shortest path to Grade C: + +[arabic] +. *Farm* — local filesystem, no network dependency +. *Provenance Map* — git blame is local +. *Filesystem Watcher* — Rust notify is already wired +. *BoJ Panel* — BoJ-server is usually running +. *VCL Panel* — VeriSimDB when running + +=== Sign-Off + +CRG D→C promotion requires Jonathan’s sign-off after dogfooding. + +* [ ] Jonathan has used PanLL for real work (not just testing) +* [ ] Issues from dogfooding sessions are filed or fixed +* [ ] TOPOLOGY.md updated with new CRG grades +* [ ] STATE.a2ml updated with promotion timestamp diff --git a/docs/CRG-DOGFOOD-CHECKLIST.md b/docs/CRG-DOGFOOD-CHECKLIST.md deleted file mode 100644 index 7ff461ef..00000000 --- a/docs/CRG-DOGFOOD-CHECKLIST.md +++ /dev/null @@ -1,76 +0,0 @@ - - - - -# CRG D→C Dogfooding Checklist - -## What Grade C Means - -Grade C (Beta) requires **real backend connections** and **author dogfooding**. -This cannot be automated — it requires Jonathan using PanLL for actual work. - -## Prerequisites (Must Be True Before Dogfooding) - -- [x] All 108 panels compile (0 errors, 0 warnings) -- [x] 2462+ tests passing -- [x] Zero dangerous patterns in source (Obj.magic, believe_me, etc.) -- [x] Gossamer backend builds (`cargo check` clean) -- [x] Dev server starts (`deno task dev`) -- [ ] VeriSimDB running on port 8093 -- [ ] BoJ-server running on port 7700 (SSE on 7703) -- [ ] ECHIDNA available on port 9000 - -## Backend Connection Verification (Minimum 4 of 9) - -Each backend must return real data, not mock JSON. - -| # | Backend | Port | Panel(s) | Status | -|---|---------|------|----------|--------| -| 1 | BoJ-server | 7700 | BoJ Panel, Automation Router | ☐ | -| 2 | VeriSimDB | 8093 | Panel-W, VCL Panel | ☐ | -| 3 | ECHIDNA | 9000 | Panel-N, Proofs Bridge | ☐ | -| 4 | gitbot-fleet | 8080 | Gitbot-Fleet Panel | ☐ | -| 5 | Hypatia | (Elixir) | Hypatia Panel | ☐ | -| 6 | Git blame | (local) | Provenance Map | ✓ code verified (2026-03-29) — provenance/commands.rs wired | -| 7 | Filesystem | (local) | Farm, Watcher | ✓ code verified (2026-03-29) — farm/commands.rs + watcher/commands.rs wired | -| 8 | TypeLL | 7800 | Cross-panel type checking | ☐ | -| 9 | Stapeln | (local) | Container management | ☐ | - -## Dogfooding Sessions (Minimum 3) - -Each session must be logged with date, duration, what was done, and issues found. - -| # | Date | Duration | What Was Done | Issues Found | Panels Promoted | -|---|------|----------|---------------|--------------|-----------------| -| 1 | | | | | | -| 2 | | | | | | -| 3 | | | | | | - -## Per-Panel C-Grade Criteria - -A panel earns CRG C when ALL of these are true: - -1. **Live data**: At least one backend returns real (not mock) data -2. **End-to-end**: User action → backend call → result displayed (full cycle) -3. **Error handling**: Network failures show meaningful error, not crash -4. **Keyboard nav**: All interactive elements reachable via Tab/Enter -5. **No stale state**: Panel reflects current backend state on refresh - -## Promotion Candidates (Easiest to Promote First) - -These panels have the shortest path to Grade C: - -1. **Farm** — local filesystem, no network dependency -2. **Provenance Map** — git blame is local -3. **Filesystem Watcher** — Rust notify is already wired -4. **BoJ Panel** — BoJ-server is usually running -5. **VCL Panel** — VeriSimDB when running - -## Sign-Off - -CRG D→C promotion requires Jonathan's sign-off after dogfooding. - -- [ ] Jonathan has used PanLL for real work (not just testing) -- [ ] Issues from dogfooding sessions are filed or fixed -- [ ] TOPOLOGY.md updated with new CRG grades -- [ ] STATE.a2ml updated with promotion timestamp diff --git a/docs/DOGFOODING-OPPORTUNITIES.adoc b/docs/DOGFOODING-OPPORTUNITIES.adoc new file mode 100644 index 00000000..28e2cfd4 --- /dev/null +++ b/docs/DOGFOODING-OPPORTUNITIES.adoc @@ -0,0 +1,92 @@ +== PanLL Dogfooding Opportunities + +Guinea pig fooding candidates — places where PanLL can use hyperpolymath +ecosystem projects instead of generic dependencies, to test interactions +and build evidence for those projects. + +=== C → Zig Swap Candidates + +[width="100%",cols="37%,18%,31%,14%",options="header",] +|=== +|Current (C/libc) |Location |Zig Replacement |Effort +|`+libc::statvfs+` disk stats |`+workspace/sysinfo.rs:107+` |Zig NIF for +system info (like Burble coprocessors) |Small + +|`+libc::kill+` process signals |`+game_preview/commands.rs:209,212+` +|Zig process management module |Small + +|`+libc::kill+` SIGSTOP/CONT/TERM |`+llm_coding/commands.rs+` (3 calls) +|Same Zig module |Small + +|Coprocessor C FFI types |`+coprocessor/mod.rs:109-119+` |Already +Zig-shaped (C calling convention = Zig native) |None needed +|=== + +=== V-lang API Candidates + +[width="99%",cols="34%,20%,30%,16%",options="header",] +|=== +|Current (Rust) |Location |V Replacement |Effort +|HTTP client to services |`+http_client.rs+` |V adapter layer (BoJ +cartridge pattern) |Medium + +|Settings serialisation |various |V API surface for config |Medium +|=== + +=== Proven Library Integration Candidates + +[width="100%",cols="23%,23%,35%,19%",options="header",] +|=== +|Current |Location |Proven Module |Status +|reqwest URL construction |`+http_client.rs+` |`+proven/SafeHTTP+`, +`+proven/SafeUrl+` |0 believe_me + +|File path handling |`+workspace/*.rs+` |`+proven/SafeString+` |0 +believe_me + +|Version strings |config files |`+proven/SafeSemVer+` |0 believe_me + +|Any crypto/hashing |future VeriSimDB integration |`+proven/SafeHash+` +|0 believe_me +|=== + +=== VeriSimDB Integration (everything-first approach) + +[width="100%",cols="37%,39%,24%",options="header",] +|=== +|Data Category |What to persist |Priority +|Panel state |Open/closed, position, size, scroll position per panel |P0 + +|Workspace layouts |Named layout snapshots, auto-save current layout |P0 + +|User settings |Preferences, theme, keybindings, accessibility |P0 + +|Multiuser perspectives |Full workspace snapshot per team member — "`see +the world from their view`" |P1 + +|Session recordings |Command history, panel interactions, timestamps |P1 + +|Undo history |Full undo/redo stack with branching |P1 + +|Panel usage analytics |Which panels used most, interaction patterns |P2 + +|Collaboration state |Shared cursors, live presence, team annotations +|P2 + +|Build/test results |CI output, test traces, build metrics |P2 + +|ECHIDNA proof traces |Tactic predictions, premise rankings, proof +search paths |P2 + +|Keystroke heatmaps |Input frequency per panel (accessibility + UX +research) |P3 +|=== + +=== Notes + +* This is guinea pig fooding — we’re testing ecosystem interactions, not +optimising +* Some of these will prove not valuable — that’s fine, strip them back +later +* The portfolio of VeriSimDB use cases IS the evidence for the project +* Every integration is a potential paper example or demo diff --git a/docs/DOGFOODING-OPPORTUNITIES.md b/docs/DOGFOODING-OPPORTUNITIES.md deleted file mode 100644 index 80381422..00000000 --- a/docs/DOGFOODING-OPPORTUNITIES.md +++ /dev/null @@ -1,53 +0,0 @@ -# PanLL Dogfooding Opportunities - -Guinea pig fooding candidates — places where PanLL can use hyperpolymath -ecosystem projects instead of generic dependencies, to test interactions -and build evidence for those projects. - -## C → Zig Swap Candidates - -| Current (C/libc) | Location | Zig Replacement | Effort | -|-------------------|----------|-----------------|--------| -| `libc::statvfs` disk stats | `workspace/sysinfo.rs:107` | Zig NIF for system info (like Burble coprocessors) | Small | -| `libc::kill` process signals | `game_preview/commands.rs:209,212` | Zig process management module | Small | -| `libc::kill` SIGSTOP/CONT/TERM | `llm_coding/commands.rs` (3 calls) | Same Zig module | Small | -| Coprocessor C FFI types | `coprocessor/mod.rs:109-119` | Already Zig-shaped (C calling convention = Zig native) | None needed | - -## V-lang API Candidates - -| Current (Rust) | Location | V Replacement | Effort | -|----------------|----------|---------------|--------| -| HTTP client to services | `http_client.rs` | V adapter layer (BoJ cartridge pattern) | Medium | -| Settings serialisation | various | V API surface for config | Medium | - -## Proven Library Integration Candidates - -| Current | Location | Proven Module | Status | -|---------|----------|---------------|--------| -| reqwest URL construction | `http_client.rs` | `proven/SafeHTTP`, `proven/SafeUrl` | 0 believe_me | -| File path handling | `workspace/*.rs` | `proven/SafeString` | 0 believe_me | -| Version strings | config files | `proven/SafeSemVer` | 0 believe_me | -| Any crypto/hashing | future VeriSimDB integration | `proven/SafeHash` | 0 believe_me | - -## VeriSimDB Integration (everything-first approach) - -| Data Category | What to persist | Priority | -|---------------|----------------|----------| -| Panel state | Open/closed, position, size, scroll position per panel | P0 | -| Workspace layouts | Named layout snapshots, auto-save current layout | P0 | -| User settings | Preferences, theme, keybindings, accessibility | P0 | -| Multiuser perspectives | Full workspace snapshot per team member — "see the world from their view" | P1 | -| Session recordings | Command history, panel interactions, timestamps | P1 | -| Undo history | Full undo/redo stack with branching | P1 | -| Panel usage analytics | Which panels used most, interaction patterns | P2 | -| Collaboration state | Shared cursors, live presence, team annotations | P2 | -| Build/test results | CI output, test traces, build metrics | P2 | -| ECHIDNA proof traces | Tactic predictions, premise rankings, proof search paths | P2 | -| Keystroke heatmaps | Input frequency per panel (accessibility + UX research) | P3 | - -## Notes - -- This is guinea pig fooding — we're testing ecosystem interactions, not optimising -- Some of these will prove not valuable — that's fine, strip them back later -- The portfolio of VeriSimDB use cases IS the evidence for the project -- Every integration is a potential paper example or demo diff --git a/docs/TECHNICAL_DEBT.adoc b/docs/TECHNICAL_DEBT.adoc new file mode 100644 index 00000000..bae5eeac --- /dev/null +++ b/docs/TECHNICAL_DEBT.adoc @@ -0,0 +1,200 @@ +== PanLL Technical Debt Registry — 30-Day Plan + +____ +*Reset note (2026-05-17):* The previous version of this file described a +"`v0.2.0 Panic Attack Remediation`" dated 2024-04-15 with placeholder +metadata and fabricated progress counters. Its two P0 blockers and all +three "`commented out`" modules were already resolved by commit +`+6ae4336 fix(gossamer): resolve P0/P1 type mismatches, wire http_client, enable settings+`. +This document has been rewritten against the *verified state of the +tree* and recast as a dated 30-day plan. +____ + +=== Verified Baseline (2026-05-17) + +`+cargo check+` *passes* (8 dead-code warnings, 0 errors). The Gossamer +backend builds. Status of the historic items: + +[width="100%",cols="50%,50%",options="header",] +|=== +|Historic item |Verified state +|`+http_client+` module |✅ Implemented +(`+src-gossamer/src/http_client.rs+`, wired at `+main.rs:48+`). No unit +tests yet. + +|Command result type mismatches |✅ Resolved — +`+result_to_json+`/`+result_str_to_json+` return +`+Result+`; build green. + +|`+groove+` / `+settings+` / `+llm_coding+` modules |✅ All present and +wired (`+groove.rs+`, `+settings.rs+`, +`+llm_coding/{mod,commands,types}.rs+`). + +|Unused doc comment `+main.rs:38+` |✅ Obsolete reference — line 38 is +now `+mod settings;+`. +|=== + +==== Remaining Debt (the real backlog) + +[width="100%",cols="12%,15%,26%,26%,21%",options="header",] +|=== +|ID |Item |Location |Severity |Status +|D1 |Service registry mutability: register/unregister/list commands +commented out |`+src-gossamer/src/main.rs+` |High |✅ Resolved — fixed +env-set design; `+service_list+` + `+service_set_url+` wired; vestigial +register/unregister stubs removed + +|D2 |8 dead-code warnings |`+service_registry.rs+`, `+settings.rs+`, +`+llm_coding/+` |Medium |✅ Resolved — +`+get_registry+`/`+update_service_url+`/`+settings_save+`/`+read_system_memory+`+`+SystemResources+` +wired; `+WorkspaceLock+`/`+PendingAction+`/`+SpawnRequest.task_list+` +removed; clippy `+-D warnings+` clean + +|D3 |No unit tests for `+http_client.rs+` or `+service_registry.rs+` +|`+src-gossamer/src/+` |High |✅ Resolved — required a *lib/bin split* +(see below); 23 tests now run via `+cargo test --lib+` with no GTK link + +|D4 |6 TODOs: dynamic plugin loading stubbed pending +`+libloading+`/`+once_cell+` deps +|`+src-gossamer/src/coprocessor/{mod,commands}.rs+` |Medium |✅ Resolved +— `+libloading 0.8+` added (`+once_cell+` was already a dep); real +`+dlopen+`+`+copro_init+` and real `+copro_dispatch+`/`+copro_free+` +symbol calls. *Caveat:* `+coprocessor+` was orphaned (declared by no +crate root → never compiled); now wired into the lib so the fix is real +and tested + +|D5 |Stale doc: wrong date, placeholder maintainer, broken +`+docs/ARCHITECTURE.md+` link, fabricated stats |this file |Low |✅ +Resolved — rewritten 2026-05-17; real arch doc is +`+docs/architecture/ARCHITECTURE.md+` +|=== + +''''' + +=== Execution Log + +The 30-day plan was executed in a single accelerated session on +*2026-05-17* (CAP order preserved: corrective → adaptive → perfective). + +==== Week 1 — Corrective ✅ (commit `+7c7203d+`) + +* *D5* doc rewritten; arch link repointed to +`+docs/architecture/ARCHITECTURE.md+`. +* *D1* registry resolved as a fixed env-driven set: `+service_list+` +(`+get_registry+`) + `+service_set_url+` (`+update_service_url+`) wired; +vestigial `+service_register+`/`+service_unregister+` stubs removed. +* *D2* `+settings_save+` + `+llm_coding_system_resources+` wired (with a +real `+/proc/stat+` CPU sampler); `+WorkspaceLock+`, `+PendingAction+`, +`+SpawnRequest.task_list+` removed. Two pre-existing clippy lints fixed. +* Gate: `+cargo clippy --all-targets -- -D warnings+` clean. + +==== Week 2 — Adaptive (FFI) ✅ (commit `+8812d7f+`) + +* *D4* `+libloading 0.8+` added; `+FfiState+` owns the loaded +`+Library+`; `+coprocessor_load_ffi+` does a real `+dlopen+` + +`+copro_init+`; `+coprocessor_ffi_dispatch+` resolves and calls +`+copro_dispatch+`/`+copro_free+`. +* De-Tauri’d coprocessor comments; removed stale TODOs. + +==== Week 3 — Adaptive (tests) + architectural fix ✅ (commit `+bd62aef+`) + +* *Lib/bin split*: new `+[lib] panll+` (GTK-free) holds `+http_client+`, +`+service_registry+`, `+settings+`, `+identity+`, `+groove+`, +`+llm_coding+`, `+coprocessor+`. `+main.rs+` keeps only `+system_tray+` +(needs `+gossamer_rs+`). +* *D3* 23 tests run via `+cargo test --lib+` *without* linking +libgossamer/GTK. The orphaned `+coprocessor+` was wired into the lib (11 +latent clippy lints cleared once it actually compiled). + +==== Week 4 — Perfective ✅ (this commit) + +* Cross-module integration tests folded into the lib test surface. +* `+.github/hypatia-rules/panll-v0.2.0-fixes.yml+` reconciled v1 → v2: +retired all 8 false-positive panic-attack rules; one precise regression +guard (`+panll-cmd-disabled+`) kept; clippy `+-D warnings+` documented +as the gate. +* `+CHANGELOG.md+` updated. +* Final gate: `+cargo test --lib+` 23/23; +`+cargo clippy --all-targets -- -D warnings+` clean. + +=== Environment Caveat (honest) + +`+cargo test --lib+` and all `+cargo clippy+`/`+cargo check+` pass in +this WSL box. *Linking the `+panll-gossamer+` binary still fails here* — +`+libgossamer+`, `+libgtk-3+`, `+libwebkit2gtk-4.1+` are not installed. +This is a pre-existing environment gap, unrelated to these changes, and +the entire reason the lib/bin split was necessary: it moves all testable +logic out from behind the GTK link wall. The binary builds in a +GTK-equipped environment / CI. + +=== Follow-up Debt Discovered (not in original scope) + +[width="100%",cols="20%,30%,50%",options="header",] +|=== +|ID |Item |Severity +|F1 |*38 unwired PanLL panel backends* under `+src-gossamer/src/+` +(aerie=net diagnostics, hypatia=neurosym scanner, ai=multi-provider AI, +farm, provenance, k9, governance, …; ~19,181 LOC). NOT dead code — real +panel backends orphaned by the same defect as `+coprocessor+` (declared +by no crate root → never compiled → IPC commands never registered). +*Decision (2026-05-17): integrate, not delete.* Also carry stale Tauri +refs. Tracked as the F1 integration workstream. |High (lost +functionality) + +|F2 |`+coprocessor+`’s async command handlers are implemented + tested +but *not registered* in the binary’s IPC table (`+main.rs+`). Wire them +— this is the *pilot* for F1 (establishes the async→sync `+app.command+` +bridge), done first. |Medium + +|F3 |Binary cannot be built/linked locally without GTK/WebKit + a built +`+libgossamer+`. Document the dev-env setup or provide a container. +|Medium +|=== + +==== F1 integration workstream (multi-session) + +[arabic] +. *Pilot (F2):* finish `+coprocessor+` IPC registration → builds the +reusable async→sync `+block_on+` bridge for `+app.command+`. +. *Census:* declare all 38 modules; `+cargo check+` each; record which +compile clean vs. bit-rotted (never compiled — expect API drift). +. *Bulk wire* in dependency/risk order using the proven pattern; +de-Tauri as we go; cross-check command names against the ReScript +frontend `+invoke()+` contract so we wire what the UI actually calls. + +''''' + +=== Progress Tracking (live — update on every change) + +.... +Original debt items: 5 (D1–D5) +Resolved: 5 (all — 2026-05-17) +Follow-up debt opened: 3 (F1–F3, see above) +Build status: cargo check / clippy green; bin link needs GTK env +Clippy -D warnings: clean (0, all targets) +Lib tests: 23 passing (cargo test --lib, GTK-free) +.... + +=== Success Criteria + +* [x] D1–D5 all resolved or explicitly closed with rationale. +* [x] `+cargo clippy --all-targets -- -D warnings+` clean. +* [x] `+http_client+` and `+service_registry+` have unit tests in +`+cargo test+`. +* [x] No commented-out command handlers in `+main.rs+`. +* [x] Hypatia rules reflect actual current debt (no rules for resolved +items). +* [ ] F1–F3 follow-up debt triaged (next cycle). + +=== Related + +* `+docs/architecture/ARCHITECTURE.md+` — architecture reference +* `+.github/hypatia-rules/panll-v0.2.0-fixes.yml+` — reconciled v2 +(regression guard only) +* `+CONTRIBUTING.md+` +* `+CHANGELOG.md+` + +''''' + +*Last Updated:* 2026-05-17 *Plan window:* 2026-05-17 → 2026-06-15 +*Maintainer:* Jonathan Jewell (hyperpolymath) diff --git a/docs/TECHNICAL_DEBT.md b/docs/TECHNICAL_DEBT.md deleted file mode 100644 index e865c0fa..00000000 --- a/docs/TECHNICAL_DEBT.md +++ /dev/null @@ -1,132 +0,0 @@ -# PanLL Technical Debt Registry — 30-Day Plan - -> **Reset note (2026-05-17):** The previous version of this file described a -> "v0.2.0 Panic Attack Remediation" dated 2024-04-15 with placeholder -> metadata and fabricated progress counters. Its two P0 blockers and all -> three "commented out" modules were already resolved by commit -> `6ae4336 fix(gossamer): resolve P0/P1 type mismatches, wire http_client, -> enable settings`. This document has been rewritten against the **verified -> state of the tree** and recast as a dated 30-day plan. - -## Verified Baseline (2026-05-17) - -`cargo check` **passes** (8 dead-code warnings, 0 errors). The Gossamer -backend builds. Status of the historic items: - -| Historic item | Verified state | -|---|---| -| `http_client` module | ✅ Implemented (`src-gossamer/src/http_client.rs`, wired at `main.rs:48`). No unit tests yet. | -| Command result type mismatches | ✅ Resolved — `result_to_json`/`result_str_to_json` return `Result`; build green. | -| `groove` / `settings` / `llm_coding` modules | ✅ All present and wired (`groove.rs`, `settings.rs`, `llm_coding/{mod,commands,types}.rs`). | -| Unused doc comment `main.rs:38` | ✅ Obsolete reference — line 38 is now `mod settings;`. | - -### Remaining Debt (the real backlog) - -| ID | Item | Location | Severity | Status | -|----|------|----------|----------|--------| -| D1 | Service registry mutability: register/unregister/list commands commented out | `src-gossamer/src/main.rs` | High | ✅ Resolved — fixed env-set design; `service_list` + `service_set_url` wired; vestigial register/unregister stubs removed | -| D2 | 8 dead-code warnings | `service_registry.rs`, `settings.rs`, `llm_coding/` | Medium | ✅ Resolved — `get_registry`/`update_service_url`/`settings_save`/`read_system_memory`+`SystemResources` wired; `WorkspaceLock`/`PendingAction`/`SpawnRequest.task_list` removed; clippy `-D warnings` clean | -| D3 | No unit tests for `http_client.rs` or `service_registry.rs` | `src-gossamer/src/` | High | ✅ Resolved — required a **lib/bin split** (see below); 23 tests now run via `cargo test --lib` with no GTK link | -| D4 | 6 TODOs: dynamic plugin loading stubbed pending `libloading`/`once_cell` deps | `src-gossamer/src/coprocessor/{mod,commands}.rs` | Medium | ✅ Resolved — `libloading 0.8` added (`once_cell` was already a dep); real `dlopen`+`copro_init` and real `copro_dispatch`/`copro_free` symbol calls. **Caveat:** `coprocessor` was orphaned (declared by no crate root → never compiled); now wired into the lib so the fix is real and tested | -| D5 | Stale doc: wrong date, placeholder maintainer, broken `docs/ARCHITECTURE.md` link, fabricated stats | this file | Low | ✅ Resolved — rewritten 2026-05-17; real arch doc is `docs/architecture/ARCHITECTURE.md` | - ---- - -## Execution Log - -The 30-day plan was executed in a single accelerated session on **2026-05-17** -(CAP order preserved: corrective → adaptive → perfective). - -### Week 1 — Corrective ✅ (commit `7c7203d`) -- **D5** doc rewritten; arch link repointed to `docs/architecture/ARCHITECTURE.md`. -- **D1** registry resolved as a fixed env-driven set: `service_list` - (`get_registry`) + `service_set_url` (`update_service_url`) wired; vestigial - `service_register`/`service_unregister` stubs removed. -- **D2** `settings_save` + `llm_coding_system_resources` wired (with a real - `/proc/stat` CPU sampler); `WorkspaceLock`, `PendingAction`, - `SpawnRequest.task_list` removed. Two pre-existing clippy lints fixed. -- Gate: `cargo clippy --all-targets -- -D warnings` clean. - -### Week 2 — Adaptive (FFI) ✅ (commit `8812d7f`) -- **D4** `libloading 0.8` added; `FfiState` owns the loaded `Library`; - `coprocessor_load_ffi` does a real `dlopen` + `copro_init`; - `coprocessor_ffi_dispatch` resolves and calls `copro_dispatch`/`copro_free`. -- De-Tauri'd coprocessor comments; removed stale TODOs. - -### Week 3 — Adaptive (tests) + architectural fix ✅ (commit `bd62aef`) -- **Lib/bin split**: new `[lib] panll` (GTK-free) holds `http_client`, - `service_registry`, `settings`, `identity`, `groove`, `llm_coding`, - `coprocessor`. `main.rs` keeps only `system_tray` (needs `gossamer_rs`). -- **D3** 23 tests run via `cargo test --lib` **without** linking - libgossamer/GTK. The orphaned `coprocessor` was wired into the lib (11 - latent clippy lints cleared once it actually compiled). - -### Week 4 — Perfective ✅ (this commit) -- Cross-module integration tests folded into the lib test surface. -- `.github/hypatia-rules/panll-v0.2.0-fixes.yml` reconciled v1 → v2: retired - all 8 false-positive panic-attack rules; one precise regression guard - (`panll-cmd-disabled`) kept; clippy `-D warnings` documented as the gate. -- `CHANGELOG.md` updated. -- Final gate: `cargo test --lib` 23/23; `cargo clippy --all-targets -- -D warnings` clean. - -## Environment Caveat (honest) - -`cargo test --lib` and all `cargo clippy`/`cargo check` pass in this WSL box. -**Linking the `panll-gossamer` binary still fails here** — `libgossamer`, -`libgtk-3`, `libwebkit2gtk-4.1` are not installed. This is a pre-existing -environment gap, unrelated to these changes, and the entire reason the -lib/bin split was necessary: it moves all testable logic out from behind the -GTK link wall. The binary builds in a GTK-equipped environment / CI. - -## Follow-up Debt Discovered (not in original scope) - -| ID | Item | Severity | -|----|------|----------| -| F1 | **38 unwired PanLL panel backends** under `src-gossamer/src/` (aerie=net diagnostics, hypatia=neurosym scanner, ai=multi-provider AI, farm, provenance, k9, governance, …; ~19,181 LOC). NOT dead code — real panel backends orphaned by the same defect as `coprocessor` (declared by no crate root → never compiled → IPC commands never registered). **Decision (2026-05-17): integrate, not delete.** Also carry stale Tauri refs. Tracked as the F1 integration workstream. | High (lost functionality) | -| F2 | `coprocessor`'s async command handlers are implemented + tested but **not registered** in the binary's IPC table (`main.rs`). Wire them — this is the **pilot** for F1 (establishes the async→sync `app.command` bridge), done first. | Medium | -| F3 | Binary cannot be built/linked locally without GTK/WebKit + a built `libgossamer`. Document the dev-env setup or provide a container. | Medium | - -### F1 integration workstream (multi-session) - -1. **Pilot (F2):** finish `coprocessor` IPC registration → builds the - reusable async→sync `block_on` bridge for `app.command`. -2. **Census:** declare all 38 modules; `cargo check` each; record which - compile clean vs. bit-rotted (never compiled — expect API drift). -3. **Bulk wire** in dependency/risk order using the proven pattern; - de-Tauri as we go; cross-check command names against the ReScript - frontend `invoke()` contract so we wire what the UI actually calls. - ---- - -## Progress Tracking (live — update on every change) - -``` -Original debt items: 5 (D1–D5) -Resolved: 5 (all — 2026-05-17) -Follow-up debt opened: 3 (F1–F3, see above) -Build status: cargo check / clippy green; bin link needs GTK env -Clippy -D warnings: clean (0, all targets) -Lib tests: 23 passing (cargo test --lib, GTK-free) -``` - -## Success Criteria - -- [x] D1–D5 all resolved or explicitly closed with rationale. -- [x] `cargo clippy --all-targets -- -D warnings` clean. -- [x] `http_client` and `service_registry` have unit tests in `cargo test`. -- [x] No commented-out command handlers in `main.rs`. -- [x] Hypatia rules reflect actual current debt (no rules for resolved items). -- [ ] F1–F3 follow-up debt triaged (next cycle). - -## Related - -- `docs/architecture/ARCHITECTURE.md` — architecture reference -- `.github/hypatia-rules/panll-v0.2.0-fixes.yml` — reconciled v2 (regression guard only) -- `CONTRIBUTING.md` -- `CHANGELOG.md` - ---- - -**Last Updated:** 2026-05-17 -**Plan window:** 2026-05-17 → 2026-06-15 -**Maintainer:** Jonathan Jewell (hyperpolymath) diff --git a/docs/TODO.adoc b/docs/TODO.adoc new file mode 100644 index 00000000..d0370beb --- /dev/null +++ b/docs/TODO.adoc @@ -0,0 +1,42 @@ +== PanLL TODO List + +This list summarizes active tasks and is synchronized with the +https://github.com/users/hyperpolymath/projects[GitHub Project Boards]. + +=== 🔴 Release-Blocking (v0.2.0) + +* [ ] Implement `+http_client+` module in +`+src-gossamer/src/service_registry.rs+` +* [ ] Fix command result type mismatches in `+src-gossamer/src/main.rs+` +* [ ] Finalize Reposystem event chain integration in Panel-W +* [ ] Resolve `+cargo build+` errors in `+src-gossamer/+` (281 errors +remaining) + +=== 🟡 High Priority + +* [ ] Implement `+settings+` module for user configuration +* [ ] Re-enable `+groove+` module for discovery +* [ ] Complete `+llm_coding+` session management implementation +* [ ] Replace localStorage with VeriSimDB-backed persistence + +=== 🔵 Medium Priority + +* [ ] Dark/Light theme support following system preferences +* [ ] Onboarding tutorial for first-run experience +* [ ] Increase test coverage to 95%+ +* [ ] Performance benchmarks for startup and query latency + +=== 🟢 Documentation & Maintenance + +* [ ] Complete `+0-AI-MANIFEST.a2ml+` audit +* [ ] Standardize `+.adoc+` vs `+.md+` for documentation +* [ ] Generate API reference documentation +* [ ] Finalize "`Binary Star`" paper draft + +''''' + +*Track live progress:* * +https://github.com/users/hyperpolymath/projects/33[PanLL Roadmap (33)] * +https://github.com/users/hyperpolymath/projects/26[PanLL Kanban (26)] * +https://github.com/users/hyperpolymath/projects/17[PanLL Bug Tracker +(17)] diff --git a/docs/TODO.md b/docs/TODO.md deleted file mode 100644 index ee721e63..00000000 --- a/docs/TODO.md +++ /dev/null @@ -1,33 +0,0 @@ -# PanLL TODO List - -This list summarizes active tasks and is synchronized with the [GitHub Project Boards](https://github.com/users/hyperpolymath/projects). - -## 🔴 Release-Blocking (v0.2.0) -* [ ] Implement `http_client` module in `src-gossamer/src/service_registry.rs` -* [ ] Fix command result type mismatches in `src-gossamer/src/main.rs` -* [ ] Finalize Reposystem event chain integration in Panel-W -* [ ] Resolve `cargo build` errors in `src-gossamer/` (281 errors remaining) - -## 🟡 High Priority -* [ ] Implement `settings` module for user configuration -* [ ] Re-enable `groove` module for discovery -* [ ] Complete `llm_coding` session management implementation -* [ ] Replace localStorage with VeriSimDB-backed persistence - -## 🔵 Medium Priority -* [ ] Dark/Light theme support following system preferences -* [ ] Onboarding tutorial for first-run experience -* [ ] Increase test coverage to 95%+ -* [ ] Performance benchmarks for startup and query latency - -## 🟢 Documentation & Maintenance -* [ ] Complete `0-AI-MANIFEST.a2ml` audit -* [ ] Standardize `.adoc` vs `.md` for documentation -* [ ] Generate API reference documentation -* [ ] Finalize "Binary Star" paper draft - ---- -**Track live progress:** -* [PanLL Roadmap (33)](https://github.com/users/hyperpolymath/projects/33) -* [PanLL Kanban (26)](https://github.com/users/hyperpolymath/projects/26) -* [PanLL Bug Tracker (17)](https://github.com/users/hyperpolymath/projects/17) diff --git a/docs/admin-guide.md b/docs/admin-guide.adoc similarity index 64% rename from docs/admin-guide.md rename to docs/admin-guide.adoc index cb59e20d..b238b229 100644 --- a/docs/admin-guide.md +++ b/docs/admin-guide.adoc @@ -1,62 +1,70 @@ -# PanLL Administrator Guide +== PanLL Administrator Guide -## Overview +=== Overview -This guide provides comprehensive information for system administrators responsible for deploying, configuring, and maintaining PanLL Connected Workbench in production environments. +This guide provides comprehensive information for system administrators +responsible for deploying, configuring, and maintaining PanLL Connected +Workbench in production environments. -## Table of Contents +=== Table of Contents -1. [System Requirements](#system-requirements) -2. [Installation](#installation) -3. [Configuration](#configuration) -4. [Service Management](#service-management) -5. [Monitoring & Maintenance](#monitoring--maintenance) -6. [Security](#security) -7. [Troubleshooting](#troubleshooting) -8. [Backup & Recovery](#backup--recovery) -9. [Scaling & Performance](#scaling--performance) -10. [Upgrade Procedures](#upgrade-procedures) +[arabic] +. link:#system-requirements[System Requirements] +. link:#installation[Installation] +. link:#configuration[Configuration] +. link:#service-management[Service Management] +. link:++#monitoring--maintenance++[Monitoring & Maintenance] +. link:#security[Security] +. link:#troubleshooting[Troubleshooting] +. link:++#backup--recovery++[Backup & Recovery] +. link:++#scaling--performance++[Scaling & Performance] +. link:#upgrade-procedures[Upgrade Procedures] -## System Requirements +=== System Requirements -### Minimum Requirements +==== Minimum Requirements -| Component | Requirement | -|-----------|-------------| -| **Operating System** | Linux (Ubuntu 22.04+, Fedora 38+, Debian 11+) | -| **CPU** | 2 cores, x86_64 | -| **RAM** | 4GB | -| **Disk Space** | 500MB (1GB+ recommended for snapshots) | -| **Network** | 10Mbps connection | +[cols=",",options="header",] +|=== +|Component |Requirement +|*Operating System* |Linux (Ubuntu 22.04+, Fedora 38+, Debian 11+) +|*CPU* |2 cores, x86_64 +|*RAM* |4GB +|*Disk Space* |500MB (1GB+ recommended for snapshots) +|*Network* |10Mbps connection +|=== -### Recommended Requirements +==== Recommended Requirements -| Component | Requirement | -|-----------|-------------| -| **Operating System** | Linux (Ubuntu 22.04 LTS) | -| **CPU** | 4 cores, x86_64 | -| **RAM** | 8GB+ | -| **Disk Space** | 10GB+ (SSD recommended) | -| **Network** | 100Mbps+ connection | +[cols=",",options="header",] +|=== +|Component |Requirement +|*Operating System* |Linux (Ubuntu 22.04 LTS) +|*CPU* |4 cores, x86_64 +|*RAM* |8GB+ +|*Disk Space* |10GB+ (SSD recommended) +|*Network* |100Mbps+ connection +|=== -### Supported Architectures +==== Supported Architectures -- **x86_64**: Fully supported -- **ARM64**: Experimental support (v0.2.1+) -- **RISC-V**: Not supported +* *x86_64*: Fully supported +* *ARM64*: Experimental support (v0.2.1+) +* *RISC-V*: Not supported -### Browser Requirements (for web UI) +==== Browser Requirements (for web UI) -- Chrome 110+ -- Firefox 109+ -- Safari 16+ -- Edge 110+ +* Chrome 110+ +* Firefox 109+ +* Safari 16+ +* Edge 110+ -## Installation +=== Installation -### Prerequisites +==== Prerequisites -```bash +[source,bash] +---- # Install required dependencies (Ubuntu/Debian) sudo apt update sudo apt install -y \ @@ -77,13 +85,14 @@ source $HOME/.cargo/env curl -fsSL https://deno.land/x/install/install.sh | sh export DENO_INSTALL="/home/$USER/.deno" export PATH="$DENO_INSTALL/bin:$PATH" -``` +---- -### Installation Methods +==== Installation Methods -#### Method 1: Pre-built Binaries (Recommended) +===== Method 1: Pre-built Binaries (Recommended) -```bash +[source,bash] +---- # Download latest release wget https://github.com/hyperpolymath/panll/releases/download/v0.2.0/panll-v0.2.0-linux-x86_64.tar.gz @@ -93,11 +102,12 @@ cd panll-v0.2.0-linux-x86_64 # Install sudo ./install.sh -``` +---- -#### Method 2: From Source +===== Method 2: From Source -```bash +[source,bash] +---- # Clone repository git clone https://github.com/hyperpolymath/panll.git cd panll @@ -110,11 +120,12 @@ cargo build --release # Install sudo cp target/release/panll-gossamer /usr/local/bin/panll -``` +---- -#### Method 3: Docker (Experimental) +===== Method 3: Docker (Experimental) -```bash +[source,bash] +---- # Pull image docker pull ghcr.io/hyperpolymath/panll:v0.2.0 @@ -125,11 +136,12 @@ docker run -d \ -v /var/panll/data:/data \ -v /var/panll/config:/config \ ghcr.io/hyperpolymath/panll:v0.2.0 -``` +---- -### Post-Installation Setup +==== Post-Installation Setup -```bash +[source,bash] +---- # Create configuration directory sudo mkdir -p /etc/panll sudo chown $USER:$USER /etc/panll @@ -142,22 +154,25 @@ sudo chown $USER:$USER /var/panll sudo cp /usr/local/share/panll/panll.service /etc/systemd/system/ sudo systemctl enable panll sudo systemctl start panll -``` +---- -## Configuration +=== Configuration -### Configuration Files +==== Configuration Files -| File | Purpose | -|------|---------| -| `/etc/panll/panll.config.toml` | Main configuration | -| `/etc/panll/services.toml` | Service endpoints | -| `/etc/panll/security.toml` | Security settings | -| `/etc/panll/logging.toml` | Logging configuration | +[cols=",",options="header",] +|=== +|File |Purpose +|`+/etc/panll/panll.config.toml+` |Main configuration +|`+/etc/panll/services.toml+` |Service endpoints +|`+/etc/panll/security.toml+` |Security settings +|`+/etc/panll/logging.toml+` |Logging configuration +|=== -### Main Configuration (`panll.config.toml`) +==== Main Configuration (`+panll.config.toml+`) -```toml +[source,toml] +---- # PanLL Main Configuration [panll] # Application settings @@ -182,11 +197,12 @@ worker_threads = 4 base_path = "/var/panll" snapshot_dir = "identities" max_snapshot_size_mb = 10 -``` +---- -### Service Configuration (`services.toml`) +==== Service Configuration (`+services.toml+`) -```toml +[source,toml] +---- # Service Endpoints Configuration [verisimdb] url = "http://localhost:8080/api/v1" @@ -205,22 +221,25 @@ tray_icon_path = "/usr/share/panll/icons/tray-icon.png" # Additional services can be configured here [custom_services] # example_service = "http://localhost:3000" -``` +---- -### Environment Variables +==== Environment Variables -| Variable | Description | Default | -|----------|-------------|---------| -| `PANLL_CONFIG` | Path to config file | `/etc/panll/panll.config.toml` | -| `PANLL_DATA_DIR` | Data directory | `/var/panll` | -| `VERISIMDB_URL` | VeriSimDB endpoint | `http://localhost:8080/api/v1` | -| `BURBLE_URL` | Burble endpoint | `http://localhost:6473` | -| `PANLL_LOG_LEVEL` | Log level | `info` | -| `PANLL_DEBUG` | Enable debug mode | `0` | +[width="100%",cols="32%,40%,28%",options="header",] +|=== +|Variable |Description |Default +|`+PANLL_CONFIG+` |Path to config file |`+/etc/panll/panll.config.toml+` +|`+PANLL_DATA_DIR+` |Data directory |`+/var/panll+` +|`+VERISIMDB_URL+` |VeriSimDB endpoint |`+http://localhost:8080/api/v1+` +|`+BURBLE_URL+` |Burble endpoint |`+http://localhost:6473+` +|`+PANLL_LOG_LEVEL+` |Log level |`+info+` +|`+PANLL_DEBUG+` |Enable debug mode |`+0+` +|=== -### Command Line Options +==== Command Line Options -```bash +[source,bash] +---- # Show help panll --help @@ -238,13 +257,14 @@ panll --log-level debug # Show version panll --version -``` +---- -## Service Management +=== Service Management -### Systemd Service +==== Systemd Service -```bash +[source,bash] +---- # Start service sudo systemctl start panll @@ -259,11 +279,12 @@ sudo systemctl status panll # View logs journalctl -u panll -f -``` +---- -### Service Configuration +==== Service Configuration -```ini +[source,ini] +---- # /etc/systemd/system/panll.service [Unit] Description=PanLL Connected Workbench @@ -280,13 +301,14 @@ Environment="PANLL_LOG_LEVEL=info" [Install] WantedBy=multi-user.target -``` +---- -### Managing Dependencies +==== Managing Dependencies -#### VeriSimDB +===== VeriSimDB -```bash +[source,bash] +---- # Install VeriSimDB git clone https://github.com/hyperpolymath/verisimdb.git cd verisimdb @@ -299,11 +321,12 @@ cargo build --release sudo cp verisimdb.service /etc/systemd/system/ sudo systemctl enable verisimdb sudo systemctl start verisimdb -``` +---- -#### Burble +===== Burble -```bash +[source,bash] +---- # Install Burble git clone https://github.com/hyperpolymath/burble.git cd burble @@ -316,13 +339,14 @@ cargo build --release sudo cp burble.service /etc/systemd/system/ sudo systemctl enable burble sudo systemctl start burble -``` +---- -## Monitoring & Maintenance +=== Monitoring & Maintenance -### Logging +==== Logging -```bash +[source,bash] +---- # View application logs journalctl -u panll -f @@ -331,11 +355,12 @@ journalctl -u panll --since "2024-01-01" --until "2024-01-02" # Export logs journalctl -u panll --no-pager > panll.logs -``` +---- -### Log Configuration +==== Log Configuration -```toml +[source,toml] +---- # logging.toml [logging] level = "info" # trace, debug, info, warn, error @@ -350,11 +375,12 @@ format = "text" # text, json [logging.file] enabled = true format = "json" -``` +---- -### Health Checks +==== Health Checks -```bash +[source,bash] +---- # Check PanLL health curl http://localhost:8080/health @@ -380,41 +406,41 @@ echo "\n=== System Status ===" systemctl status panll --no-pager systemctl status verisimdb --no-pager systemctl status burble --no-pager -``` +---- -### Monitoring Tools +==== Monitoring Tools -#### Prometheus Metrics +===== Prometheus Metrics -```toml +[source,toml] +---- # Enable metrics in panll.config.toml [metrics] enabled = true port = 9090 path = "/metrics" -``` +---- -```yaml +[source,yaml] +---- # prometheus.yml scrape_configs: - job_name: 'panll' scrape_interval: 15s static_configs: - targets: ['localhost:9090'] -``` +---- -#### Grafana Dashboard +===== Grafana Dashboard -Import the PanLL Grafana dashboard (ID: 18742) for comprehensive monitoring: -- Identity operations -- Cache performance -- Service response times -- Error rates -- System metrics +Import the PanLL Grafana dashboard (ID: 18742) for comprehensive +monitoring: - Identity operations - Cache performance - Service response +times - Error rates - System metrics -### Maintenance Tasks +==== Maintenance Tasks -```bash +[source,bash] +---- # Cleanup old snapshots (keep last 30 days) find /var/panll/identities -name "*.json" -mtime +30 -delete @@ -429,13 +455,14 @@ du -sh /var/panll # Backup configuration cp -r /etc/panll /var/backups/panll-config-$(date +%Y%m%d) -``` +---- -## Security +=== Security -### Security Best Practices +==== Security Best Practices -```toml +[source,toml] +---- # security.toml [security] # Enable TLS for all connections @@ -455,11 +482,12 @@ cors_allowed_methods = ["GET", "POST", "PUT", "DELETE"] # Rate limiting rate_limit_requests = 100 rate_limit_window_secs = 60 -``` +---- -### TLS Configuration +==== TLS Configuration -```bash +[source,bash] +---- # Generate self-signed certificate (for testing) sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ -keyout /etc/panll/certs/key.pem \ @@ -469,79 +497,77 @@ sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ # Set proper permissions sudo chown panll:panll /etc/panll/certs/* sudo chmod 600 /etc/panll/certs/* -``` +---- -### Authentication +==== Authentication -```bash +[source,bash] +---- # Enable JWT authentication # Generate strong secret openssl rand -base64 32 # Configure in security.toml jwt_secret = "generated-secret-from-above" -``` +---- -### Security Checklist +==== Security Checklist -- [ ] Enable TLS for all services -- [ ] Rotate JWT secrets regularly -- [ ] Restrict CORS to trusted domains -- [ ] Enable rate limiting -- [ ] Set proper file permissions -- [ ] Regular security audits -- [ ] Keep dependencies updated -- [ ] Monitor for suspicious activity +* [ ] Enable TLS for all services +* [ ] Rotate JWT secrets regularly +* [ ] Restrict CORS to trusted domains +* [ ] Enable rate limiting +* [ ] Set proper file permissions +* [ ] Regular security audits +* [ ] Keep dependencies updated +* [ ] Monitor for suspicious activity -## Troubleshooting +=== Troubleshooting -### Common Issues +==== Common Issues -#### PanLL won't start +===== PanLL won’t start -**Symptoms**: Service fails to start, no error messages +*Symptoms*: Service fails to start, no error messages -**Solutions**: -1. Check logs: `journalctl -u panll -n 50` -2. Verify dependencies: `ldd /usr/local/bin/panll` -3. Check port conflicts: `ss -tulnp | grep 8080` -4. Test configuration: `panll --config /etc/panll/panll.config.toml --dev` +*Solutions*: 1. Check logs: `+journalctl -u panll -n 50+` 2. Verify +dependencies: `+ldd /usr/local/bin/panll+` 3. Check port conflicts: +`+ss -tulnp | grep 8080+` 4. Test configuration: +`+panll --config /etc/panll/panll.config.toml --dev+` -#### VeriSimDB connection failures +===== VeriSimDB connection failures -**Symptoms**: "VeriSimDB unavailable" errors +*Symptoms*: "`VeriSimDB unavailable`" errors -**Solutions**: -1. Check VeriSimDB status: `systemctl status verisimdb` -2. Test connection: `curl http://localhost:8080/api/v1/health` -3. Verify configuration: `cat /etc/panll/services.toml` -4. Check network: `ping localhost` -5. Test with fallback: `export VERISIMDB_URL="" && panll` +*Solutions*: 1. Check VeriSimDB status: `+systemctl status verisimdb+` +2. Test connection: `+curl http://localhost:8080/api/v1/health+` 3. +Verify configuration: `+cat /etc/panll/services.toml+` 4. Check network: +`+ping localhost+` 5. Test with fallback: +`+export VERISIMDB_URL="" && panll+` -#### Performance issues +===== Performance issues -**Symptoms**: Slow response times, high CPU usage +*Symptoms*: Slow response times, high CPU usage -**Solutions**: -1. Check cache settings: `grep cache /etc/panll/panll.config.toml` -2. Monitor resources: `htop` -3. Analyze queries: Enable debug logging -4. Optimize configuration: Adjust worker threads and cache size -5. Check disk I/O: `iotop` +*Solutions*: 1. Check cache settings: +`+grep cache /etc/panll/panll.config.toml+` 2. Monitor resources: +`+htop+` 3. Analyze queries: Enable debug logging 4. Optimize +configuration: Adjust worker threads and cache size 5. Check disk I/O: +`+iotop+` -#### Permission errors +===== Permission errors -**Symptoms**: "Permission denied" errors +*Symptoms*: "`Permission denied`" errors -**Solutions**: -1. Check directory permissions: `ls -la /var/panll` -2. Verify user: `whoami` -3. Fix ownership: `sudo chown -R panll:panll /var/panll` -4. Check SELinux: `getenforce` (consider `setenforce 0` for testing) +*Solutions*: 1. Check directory permissions: `+ls -la /var/panll+` 2. +Verify user: `+whoami+` 3. Fix ownership: +`+sudo chown -R panll:panll /var/panll+` 4. Check SELinux: +`+getenforce+` (consider `+setenforce 0+` for testing) -### Debugging Tools +==== Debugging Tools -```bash +[source,bash] +---- # Enable debug mode panll --dev --log-level debug @@ -556,13 +582,14 @@ valgrind --tool=massif /usr/local/bin/panll # Thread analysis strace -p $(pidof panll-gossamer) -f -e trace=process -``` +---- -## Backup & Recovery +=== Backup & Recovery -### Backup Strategy +==== Backup Strategy -```bash +[source,bash] +---- # Daily backup script #!/bin/bash # backup-panll.sh @@ -591,11 +618,12 @@ fi find $BACKUP_DIR -mtime +30 -exec rm -rf {} \; echo "Backup completed: $BACKUP_DIR/$DATE" -``` +---- -### Restore Procedure +==== Restore Procedure -```bash +[source,bash] +---- # Restore from backup #!/bin/bash # restore-panll.sh @@ -627,11 +655,12 @@ sudo systemctl start burble sudo systemctl start panll echo "Restore completed from $BACKUP_DIR" -``` +---- -### Disaster Recovery +==== Disaster Recovery -```bash +[source,bash] +---- # Emergency recovery procedure # 1. Stop all services @@ -655,13 +684,14 @@ sudo systemctl start panll # 6. Monitor journalctl -u panll -u verisimdb -u burble -f -``` +---- -## Scaling & Performance +=== Scaling & Performance -### Horizontal Scaling +==== Horizontal Scaling -```toml +[source,toml] +---- # For multi-instance deployments [cluster] enabled = false @@ -672,11 +702,12 @@ discovery_url = "http://discovery-service:8080" # - Shared VeriSimDB instance # - Shared Burble instance # - Redis for coordination -``` +---- -### Performance Tuning +==== Performance Tuning -```toml +[source,toml] +---- # performance.toml [performance] # Worker pool settings @@ -696,11 +727,12 @@ db_timeout_secs = 15 # Network http_keepalive_secs = 60 http_max_connections = 500 -``` +---- -### Benchmarking +==== Benchmarking -```bash +[source,bash] +---- # Run performance benchmarks panll --benchmark --output benchmarks.json @@ -713,23 +745,24 @@ heaptrack /usr/local/bin/panll # CPU profiling perf record -g -p $(pidof panll-gossamer) sleep 30 perf report -``` +---- -## Upgrade Procedures +=== Upgrade Procedures -### Upgrade Checklist +==== Upgrade Checklist -- [ ] Review release notes -- [ ] Backup current installation -- [ ] Test upgrade in staging environment -- [ ] Notify users of maintenance window -- [ ] Perform upgrade -- [ ] Verify functionality -- [ ] Monitor for issues +* [ ] Review release notes +* [ ] Backup current installation +* [ ] Test upgrade in staging environment +* [ ] Notify users of maintenance window +* [ ] Perform upgrade +* [ ] Verify functionality +* [ ] Monitor for issues -### Upgrade from v0.1.x to v0.2.0 +==== Upgrade from v0.1.x to v0.2.0 -```bash +[source,bash] +---- # Backup existing installation sudo cp -r /etc/panll /var/backups/panll-config-pre-v0.2.0 sudo cp -r /var/panll /var/backups/panll-data-pre-v0.2.0 @@ -763,11 +796,12 @@ sudo systemctl start panll # Verify upgrade panll --version curl http://localhost:8080/health -``` +---- -### Rollback Procedure +==== Rollback Procedure -```bash +[source,bash] +---- # Stop new services sudo systemctl stop panll @@ -788,13 +822,14 @@ sudo systemctl start panll-tauri # Verify rollback panll --version -``` +---- -## Appendix +=== Appendix -### Useful Commands +==== Useful Commands -```bash +[source,bash] +---- # Check PanLL version panll --version @@ -815,11 +850,12 @@ panll --list-snapshots # Cleanup cache panll --clear-cache -``` +---- -### Configuration Reference +==== Configuration Reference -```toml +[source,toml] +---- # Complete configuration reference [panll] port = 8080 @@ -866,23 +902,28 @@ tls_enabled = false cert_file = "/etc/panll/certs/cert.pem" key_file = "/etc/panll/certs/key.pem" auth_required = false -``` +---- -### Support Resources +==== Support Resources -- **Documentation**: https://panll.hyperpolymath.dev/docs -- **GitHub Issues**: https://github.com/hyperpolymath/panll/issues -- **Discussions**: https://github.com/hyperpolymath/panll/discussions -- **Email Support**: support@hyperpolymath.dev +* *Documentation*: https://panll.hyperpolymath.dev/docs +* *GitHub Issues*: https://github.com/hyperpolymath/panll/issues +* *Discussions*: https://github.com/hyperpolymath/panll/discussions +* *Email Support*: support@hyperpolymath.dev -### Version History +==== Version History -| Version | Release Date | Notes | -|---------|---------------|-------| -| v0.2.0 | 2024-05-15 | Connected Workbench, VeriSimDB integration | -| v0.1.15 | 2024-03-10 | Final Tauri-based release | -| v0.1.0 | 2023-11-05 | Initial alpha release | +[cols=",,",options="header",] +|=== +|Version |Release Date |Notes +|v0.2.0 |2024-05-15 |Connected Workbench, VeriSimDB integration +|v0.1.15 |2024-03-10 |Final Tauri-based release +|v0.1.0 |2023-11-05 |Initial alpha release +|=== -## Conclusion +=== Conclusion -This administrator guide provides comprehensive information for deploying, configuring, and maintaining PanLL Connected Workbench. For additional assistance, refer to the official documentation or contact support. \ No newline at end of file +This administrator guide provides comprehensive information for +deploying, configuring, and maintaining PanLL Connected Workbench. For +additional assistance, refer to the official documentation or contact +support. diff --git a/docs/api-reference.adoc b/docs/api-reference.adoc new file mode 100644 index 00000000..4ba33ae4 --- /dev/null +++ b/docs/api-reference.adoc @@ -0,0 +1,358 @@ +== VeriSimDB Integration API Reference + +=== Overview + +PanLL integrates with VeriSimDB for persistent storage of identity +snapshots and other state data. This document describes the available +API endpoints and their usage. + +=== Base Configuration + +* *Default VeriSimDB URL*: `+http://localhost:8080/api/v1+` +* *Environment Variable*: `+VERISIMDB_URL+` (override default) +* *Timeout*: 10 seconds for all operations + +=== Identity Management Endpoints + +==== Save Identity Snapshot + +*Command*: `+verisim_save_state+` + +*Parameters*: + +[source,json] +---- +{ + "key": "string", // Snapshot ID (UUID) + "state": "string" // JSON string of IdentitySnapshot +} +---- + +*Returns*: + +[source,json] +---- +{ + "ok": true, + "result": "string" // Success message or VeriSimDB response +} +---- + +*Example*: + +[source,javascript] +---- +const result = await invoke("verisim_save_state", { + key: "abc123-def456", + state: JSON.stringify(snapshotData) +}); +---- + +==== Load Identity Snapshot + +*Command*: `+verisim_load_state+` + +*Parameters*: + +[source,json] +---- +{ + "key": "string" // Snapshot ID to load +} +---- + +*Returns*: + +[source,json] +---- +{ + "ok": true, + "result": { // Parsed JSON object + "id": "string", + "name": "string", + "created_at": "string", + "panll_state": "string", + "settings": "string", + "service_urls": "string" + } +} +---- + +*Example*: + +[source,javascript] +---- +const snapshot = await invoke("verisim_load_state", { + key: "abc123-def456" +}); +---- + +=== VeriSimDB Direct Access + +==== Health Check + +*Command*: `+verisim_health+` + +*Parameters*: None + +*Returns*: + +[source,json] +---- +{ + "ok": true, + "result": "string" // Health status JSON +} +---- + +==== Execute VCL Query + +*Command*: `+verisim_vcl_execute+` + +*Parameters*: + +[source,json] +---- +{ + "vcl": "string" // VCL query string +} +---- + +*Returns*: + +[source,json] +---- +{ + "ok": true, + "result": "string" // Query results JSON +} +---- + +==== List Octads + +*Command*: `+verisim_octads_list+` + +*Parameters*: + +[source,json] +---- +{ + "limit": number, // Max results (default: 100) + "offset": number // Pagination offset (default: 0) +} +---- + +*Returns*: + +[source,json] +---- +{ + "ok": true, + "result": "string" // Octads list JSON +} +---- + +==== Get Drift Entity + +*Command*: `+verisim_drift_entity+` + +*Parameters*: + +[source,json] +---- +{ + "entity_id": "string" // Entity ID to query +} +---- + +*Returns*: + +[source,json] +---- +{ + "ok": true, + "result": "string" // Entity data JSON +} +---- + +==== Trigger Normalizer + +*Command*: `+verisim_normalizer_trigger+` + +*Parameters*: + +[source,json] +---- +{ + "entity_id": "string" // Entity ID to normalize +} +---- + +*Returns*: + +[source,json] +---- +{ + "ok": true, + "result": "string" // Normalization result +} +---- + +==== Get Octads for Entity + +*Command*: `+verisim_octads_get+` + +*Parameters*: + +[source,json] +---- +{ + "entity_id": "string" // Entity ID +} +---- + +*Returns*: + +[source,json] +---- +{ + "ok": true, + "result": "string" // Octads data JSON +} +---- + +=== Orchestrator Endpoints + +==== Orchestrator Status + +*Command*: `+verisim_orch_status+` + +*Parameters*: None + +*Returns*: + +[source,json] +---- +{ + "ok": true, + "result": "string" // Orchestrator status JSON +} +---- + +=== Error Handling + +All commands return a consistent error format: + +[source,json] +---- +{ + "ok": false, + "error": "string" // Error message +} +---- + +==== Common Error Scenarios + +*VeriSimDB Unavailable*: - Automatic fallback to local filesystem +storage - Operations continue normally - Data syncs when connection +restored + +*Invalid Snapshot ID*: + +[source,json] +---- +{ + "ok": false, + "error": "Snapshot not found: abc123" +} +---- + +*Network Timeout*: + +[source,json] +---- +{ + "ok": false, + "error": "GET failed: operation timed out" +} +---- + +=== Storage Fallback Mechanism + +==== Primary → Fallback Flow + +[arabic] +. Attempt VeriSimDB operation +. On success: Return VeriSimDB response +. On failure: Fall back to local filesystem +. On filesystem success: Return local data +. On complete failure: Return error + +==== Fallback → Primary Sync + +When VeriSimDB connection is restored: 1. System automatically detects +connection 2. Local snapshots are synced to VeriSimDB 3. No manual +intervention required 4. System tray shows sync completion notification + +=== Performance Characteristics + +* *Save Operation*: ~50-150ms (VeriSimDB) / ~10-30ms (filesystem) +* *Load Operation*: ~60-200ms (VeriSimDB) / ~15-40ms (filesystem) +* *List Operation*: ~80-250ms (VeriSimDB) / ~20-50ms (filesystem) + +=== Rate Limiting + +* No explicit rate limiting from PanLL +* VeriSimDB may impose limits (configurable server-side) +* Recommended: ≤ 10 operations/second for bulk operations + +=== Authentication + +* VeriSimDB authentication handled at server level +* PanLL passes through configured credentials +* Set `+VERISIMDB_AUTH_TOKEN+` environment variable if required + +=== Best Practices + +==== Connection Management + +[source,javascript] +---- +// Check VeriSimDB health before operations +const health = await invoke("verisim_health"); +if (!health.ok) { + console.warn("VeriSimDB unavailable, using fallback storage"); +} +---- + +==== Error Handling + +[source,javascript] +---- +try { + const result = await invoke("verisim_load_state", { key: snapshotId }); + if (!result.ok) { + throw new Error(result.error); + } + // Process result +} catch (error) { + console.error("Failed to load snapshot:", error.message); + // Fallback to local storage or alternative +} +---- + +==== Batch Operations + +[source,javascript] +---- +// Process multiple snapshots efficiently +const snapshotIds = ["id1", "id2", "id3"]; +const results = await Promise.all( + snapshotIds.map(id => invoke("verisim_load_state", { key: id })) +); +---- + +=== Troubleshooting + +For common issues and solutions, see the +link:troubleshooting.md[Troubleshooting Guide]. diff --git a/docs/api-reference.md b/docs/api-reference.md deleted file mode 100644 index f7e37f9d..00000000 --- a/docs/api-reference.md +++ /dev/null @@ -1,313 +0,0 @@ -# VeriSimDB Integration API Reference - -## Overview - -PanLL integrates with VeriSimDB for persistent storage of identity snapshots and other state data. This document describes the available API endpoints and their usage. - -## Base Configuration - -- **Default VeriSimDB URL**: `http://localhost:8080/api/v1` -- **Environment Variable**: `VERISIMDB_URL` (override default) -- **Timeout**: 10 seconds for all operations - -## Identity Management Endpoints - -### Save Identity Snapshot - -**Command**: `verisim_save_state` - -**Parameters**: -```json -{ - "key": "string", // Snapshot ID (UUID) - "state": "string" // JSON string of IdentitySnapshot -} -``` - -**Returns**: -```json -{ - "ok": true, - "result": "string" // Success message or VeriSimDB response -} -``` - -**Example**: -```javascript -const result = await invoke("verisim_save_state", { - key: "abc123-def456", - state: JSON.stringify(snapshotData) -}); -``` - -### Load Identity Snapshot - -**Command**: `verisim_load_state` - -**Parameters**: -```json -{ - "key": "string" // Snapshot ID to load -} -``` - -**Returns**: -```json -{ - "ok": true, - "result": { // Parsed JSON object - "id": "string", - "name": "string", - "created_at": "string", - "panll_state": "string", - "settings": "string", - "service_urls": "string" - } -} -``` - -**Example**: -```javascript -const snapshot = await invoke("verisim_load_state", { - key: "abc123-def456" -}); -``` - -## VeriSimDB Direct Access - -### Health Check - -**Command**: `verisim_health` - -**Parameters**: None - -**Returns**: -```json -{ - "ok": true, - "result": "string" // Health status JSON -} -``` - -### Execute VCL Query - -**Command**: `verisim_vcl_execute` - -**Parameters**: -```json -{ - "vcl": "string" // VCL query string -} -``` - -**Returns**: -```json -{ - "ok": true, - "result": "string" // Query results JSON -} -``` - -### List Octads - -**Command**: `verisim_octads_list` - -**Parameters**: -```json -{ - "limit": number, // Max results (default: 100) - "offset": number // Pagination offset (default: 0) -} -``` - -**Returns**: -```json -{ - "ok": true, - "result": "string" // Octads list JSON -} -``` - -### Get Drift Entity - -**Command**: `verisim_drift_entity` - -**Parameters**: -```json -{ - "entity_id": "string" // Entity ID to query -} -``` - -**Returns**: -```json -{ - "ok": true, - "result": "string" // Entity data JSON -} -``` - -### Trigger Normalizer - -**Command**: `verisim_normalizer_trigger` - -**Parameters**: -```json -{ - "entity_id": "string" // Entity ID to normalize -} -``` - -**Returns**: -```json -{ - "ok": true, - "result": "string" // Normalization result -} -``` - -### Get Octads for Entity - -**Command**: `verisim_octads_get` - -**Parameters**: -```json -{ - "entity_id": "string" // Entity ID -} -``` - -**Returns**: -```json -{ - "ok": true, - "result": "string" // Octads data JSON -} -``` - -## Orchestrator Endpoints - -### Orchestrator Status - -**Command**: `verisim_orch_status` - -**Parameters**: None - -**Returns**: -```json -{ - "ok": true, - "result": "string" // Orchestrator status JSON -} -``` - -## Error Handling - -All commands return a consistent error format: - -```json -{ - "ok": false, - "error": "string" // Error message -} -``` - -### Common Error Scenarios - -**VeriSimDB Unavailable**: -- Automatic fallback to local filesystem storage -- Operations continue normally -- Data syncs when connection restored - -**Invalid Snapshot ID**: -```json -{ - "ok": false, - "error": "Snapshot not found: abc123" -} -``` - -**Network Timeout**: -```json -{ - "ok": false, - "error": "GET failed: operation timed out" -} -``` - -## Storage Fallback Mechanism - -### Primary → Fallback Flow - -1. Attempt VeriSimDB operation -2. On success: Return VeriSimDB response -3. On failure: Fall back to local filesystem -4. On filesystem success: Return local data -5. On complete failure: Return error - -### Fallback → Primary Sync - -When VeriSimDB connection is restored: -1. System automatically detects connection -2. Local snapshots are synced to VeriSimDB -3. No manual intervention required -4. System tray shows sync completion notification - -## Performance Characteristics - -- **Save Operation**: ~50-150ms (VeriSimDB) / ~10-30ms (filesystem) -- **Load Operation**: ~60-200ms (VeriSimDB) / ~15-40ms (filesystem) -- **List Operation**: ~80-250ms (VeriSimDB) / ~20-50ms (filesystem) - -## Rate Limiting - -- No explicit rate limiting from PanLL -- VeriSimDB may impose limits (configurable server-side) -- Recommended: ≤ 10 operations/second for bulk operations - -## Authentication - -- VeriSimDB authentication handled at server level -- PanLL passes through configured credentials -- Set `VERISIMDB_AUTH_TOKEN` environment variable if required - -## Best Practices - -### Connection Management - -```javascript -// Check VeriSimDB health before operations -const health = await invoke("verisim_health"); -if (!health.ok) { - console.warn("VeriSimDB unavailable, using fallback storage"); -} -``` - -### Error Handling - -```javascript -try { - const result = await invoke("verisim_load_state", { key: snapshotId }); - if (!result.ok) { - throw new Error(result.error); - } - // Process result -} catch (error) { - console.error("Failed to load snapshot:", error.message); - // Fallback to local storage or alternative -} -``` - -### Batch Operations - -```javascript -// Process multiple snapshots efficiently -const snapshotIds = ["id1", "id2", "id3"]; -const results = await Promise.all( - snapshotIds.map(id => invoke("verisim_load_state", { key: id })) -); -``` - -## Troubleshooting - -For common issues and solutions, see the [Troubleshooting Guide](troubleshooting.md). \ No newline at end of file diff --git a/docs/architecture/ARCHITECTURE.adoc b/docs/architecture/ARCHITECTURE.adoc new file mode 100644 index 00000000..67539af4 --- /dev/null +++ b/docs/architecture/ARCHITECTURE.adoc @@ -0,0 +1,276 @@ +== PanLL Architecture + +PanLL (pronounced "`parallel`") is a Human-Things Interface (HTI) built +with ReScript + Tauri 2.0. This document describes the major +architectural patterns. + +=== Three-Panel Layout + +The UI is split into three persistent panels: + +[width="100%",cols="33%,27%,40%",options="header",] +|=== +|Panel |Role |Content +|*Panel-L* (Symbolic Mass) |Constraints, formal specs, proofs |Type +rules, ECHIDNA verification, Anti-Crash gate + +|*Panel-N* (Neural Stream) |AI reasoning, OODA loop |Inference manifold, +confidence display, agent monologue + +|*Panel-W* (World/Barycentre) |Results, dashboards, live data |VeriSimDB +results, security findings, task outputs +|=== + +Overlay panels (41 total) appear one at a time on top of the core three. +The Panel Switcher navigation bar controls which overlay is active. At +most one overlay is visible; setting `+activePanel+` to `+None+` shows +only the core panels. + +=== TEA (The Elm Architecture) + +PanLL uses a custom TEA implementation in `+src/tea/+`. This is *not* +rescript-tea@0.16.0 — the upstream package is incompatible with the +panel architecture, so PanLL maintains its own fork. + +==== TEA Modules + +[width="100%",cols="35%,26%,39%",options="header",] +|=== +|Module |Path |Purpose +|`+Tea_App+` |`+src/tea/Tea_App.res+` |Application lifecycle — init, +update, view, subscriptions + +|`+Tea_Cmd+` |`+src/tea/Tea_Cmd.res+` |Side-effect commands — +`+Tea_Cmd.call(callbacks => ...)+` + +|`+Tea_Sub+` |`+src/tea/Tea_Sub.res+` |Subscriptions — timers, event +listeners + +|`+Tea_Html+` |`+src/tea/Tea_Html.res+` |Virtual DOM element +constructors + +|`+Tea_Vdom+` |`+src/tea/Tea_Vdom.res+` |Virtual DOM diffing and +patching + +|`+Tea_Render+` |`+src/tea/Tea_Render.res+` |DOM rendering pipeline + +|`+Tea_Time+` |`+src/tea/Tea_Time.res+` |Time-based subscriptions + +|`+Tea_Animationframe+` |`+src/tea/Tea_Animationframe.res+` +|requestAnimationFrame subscriptions + +|`+Tea+` |`+src/tea/Tea.res+` |Re-export module +|=== + +==== The Cycle + +.... + ┌──────────┐ + │ Model │ (immutable state record) + └────┬─────┘ + │ + ┌──────────▼──────────┐ + │ View(model) │ (model → Tea_Html virtual DOM) + └──────────┬──────────┘ + │ + ┌──────────▼──────────┐ + │ DOM Events │ (user clicks, key presses) + └──────────┬──────────┘ + │ + ┌──────────▼──────────┐ + │ Msg dispatched │ (variant type — exhaustive match) + └──────────┬──────────┘ + │ + ┌──────────▼──────────┐ + │ Update(model,msg) │ (returns (model, Cmd)) + └──────────┬──────────┘ + │ + ┌────▼─────┐ + │ Model' │ (new state → re-render) + └──────────┘ +.... + +Key conventions: - Commands use `+Tea_Cmd.call(callbacks => ...)+`, +never `+Tea_Cmd.promise+` - List conversion: `+->List.fromArray+` not +`+->Array.toList+` - Style attributes: +`+Attrs.style("property", "value")+` (two string args) - No JSX — all +panels use `+Tea_Html+` element constructors - `+Events.onCheck+` does +not exist — use `+Events.onClick+` + +=== Engine Pattern + +Every panel follows a consistent four-file pattern: + +.... +src/ +├── model/XxxModel.res # Types — state records, msg variants +├── core/XxxEngine.res # Pure computation — no side effects +├── commands/XxxCmd.res # Tauri invoke calls — side effects +└── components/Xxx.res # View — Tea_Html rendering +.... + +[width="100%",cols="22%,45%,33%",options="header",] +|=== +|Layer |Responsibility |Testable? +|*Model* (`+XxxModel.res+`) |Type definitions — state, messages, +sub-models |N/A (types only) + +|*Engine* (`+XxxEngine.res+`) |Pure functions — state transitions, +filtering, formatting |Yes (Deno tests) + +|*Cmd* (`+XxxCmd.res+`) |Side effects — `+Tauri.invoke+`, +`+Tea_Cmd.call+` |No (requires Tauri runtime) + +|*View* (`+Xxx.res+`) |`+Tea_Html+` rendering — maps model to virtual +DOM |Integration tests +|=== + +There are 47 engine files in `+src/core/+`. Tests import the compiled +`+.res.js+` output from engines and exercise pure functions without +needing a browser or Tauri runtime. + +=== Clade System + +Every panel belongs to a *clade* — a taxonomy entry defined in an A2ML +file under `+panel-clades/clades/+`. Clades provide: + +* *Trait inheritance*: panels inherit capabilities from parent clades +* *Kind filtering*: the Clade Browser can filter panels by kind +* *Capability queries*: +`+PanelRegistry.panelHasTrait(id, clades, getter)+` + +There are 41 clade definitions. The `+CladeBrowserEngine+` resolves +trait inheritance chains. The Rust `+clade_scanner+` module reads +`+.a2ml+` files from disk and returns them to the frontend. + +=== BoJ Gateway + +The Bundle of Joy (BoJ) server is PanLL’s primary service gateway. When +`+bojRouting+` is enabled, panels route through BoJ cartridges instead +of direct HTTP calls: + +[cols=",,",options="header",] +|=== +|Protocol |Cartridge |Panels Using +|LSP (Language Server Protocol) |`+lsp-mcp+` |Editor Bridge +|DAP (Debug Adapter Protocol) |`+dap-mcp+` |VM Inspector +|BSP (Build Server Protocol) |`+bsp-mcp+` |Build Dashboard +|Database queries |`+database-mcp+` |Databases, Panel-W +|=== + +BoJ exposes 17 cartridges total. The `+boj/+` Rust module proxies +requests to the BoJ server at `+BOJ_URL+` (default +`+http://localhost:7700/api/v1+`). The Umoja federation protocol enables +peer-to-peer cartridge sharing between BoJ instances. + +=== A2ML / K9 Integration Layer + +*A2ML* (AI Markup Language) is the manifest format for AI agents. PanLL +reads `+0-AI-MANIFEST.a2ml+` files to understand repository structure +and configure panels automatically. + +*K9* (Kennel) manages contractile configurations — validation rules and +layout constraints stored in `+.a2ml+` files. The K9 engine: - Loads +contractiles from `+Trustfile.a2ml+` - Validates panel configurations +against Yard contracts - Applies layout constraints (isolation tiers, +panel grouping) + +The `+a2ml/+` and `+k9/+` Rust modules handle file I/O; the +`+A2mlEngine+` and `+K9Engine+` ReScript modules handle pure logic. + +=== Coprocessor Engine (Phase 1-3) + +The coprocessor system offloads compute-intensive tasks: + +[width="100%",cols="31%,30%,39%",options="header",] +|=== +|Phase |Layer |Purpose +|*Phase 1* |Control plane |CPU monitoring, task queuing, device +discovery + +|*Phase 2* |Data plane (Zig FFI) |Direct FFI calls to compute engines +(Axiom.jl, etc.) + +|*Phase 3* |Smart routing |Automatic dispatch: local (CPU<80%) / remote +(neural) / BoJ (fallback) +|=== + +The `+coprocessor/+` Rust module exposes 8 commands for device +discovery, benchmarking, FFI loading, and smart dispatch. When local FFI +is unavailable, tasks fall back to BoJ cartridge invocation. + +=== Cognitive Governance + +Six ambient systems monitor operator cognitive state: + +[width="100%",cols="29%,32%,39%",options="header",] +|=== +|System |Purpose |Mechanism +|*Vexometer* |Friction monitoring |Tracks cancellations + corrections, +decays over 120s + +|*Anti-Crash Gate* |Circuit breaker |Validates neural output before it +reaches Panel-W + +|*Orbital Drift Aura* |Stability indicator |Ambient visual cue for +system health + +|*Feedback-O-Tron* |Performance reporting |Community-driven constraint +suggestions + +|*Information Humidity* |UI density adaptation |High/Medium/Low modes +adjust information density + +|*Dark Start* |Entry point |Architecture manifold bootstrapping +|=== + +These are not standalone panels — they operate as always-present +subsystems that influence the entire UI surface. + +=== Backend Architecture + +.... +┌─────────────────────────┐ +│ ReScript Frontend │ 245 .res files, compiled to JS +│ (TEA cycle) │ +└────────┬────────────────┘ + │ Tauri invoke() +┌────────▼────────────────┐ +│ Rust Backend (Tauri) │ 77 .rs files, 246 commands +│ src-tauri/src/ │ 26 modules + main.rs +└────────┬────────────────┘ + │ HTTP / WebSocket / CLI +┌────────▼────────────────┐ +│ External Services │ +│ - BoJ Server (:7700) │ +│ - TypeLL Server (:7800)│ +│ - ECHIDNA (V-lang) │ +│ - Phoenix (:4000) │ +│ - Cloudflare API │ +│ - panic-attack CLI │ +│ - protocol-squisher CLI│ +│ - my-lang CLI │ +└─────────────────────────┘ +.... + +=== Directory Structure + +.... +panll/ +├── src/ # ReScript frontend +│ ├── tea/ # Custom TEA implementation (8 modules) +│ ├── model/ # Type definitions (XxxModel.res) +│ ├── core/ # Pure engines (XxxEngine.res) — 47 files +│ ├── commands/ # Tauri invoke wrappers (XxxCmd.res) +│ ├── components/ # View functions (Xxx.res) +│ └── modules/ # Cross-cutting modules (PanelRegistry, etc.) +├── src-tauri/src/ # Rust backend +│ ├── main.rs # Entry point, invoke_handler registration +│ └── /commands.rs # Per-module Tauri commands +├── tests/ # Deno test files (45 files) +├── panel-clades/clades/ # A2ML clade definitions (41 clades) +├── public/ # Static assets, index.html +├── docs/ # Documentation +├── beam/panll_beam/ # Optional Elixir/BEAM middleware +└── deno.json # Task runner and import map +.... diff --git a/docs/architecture/ARCHITECTURE.md b/docs/architecture/ARCHITECTURE.md deleted file mode 100644 index 0a9c4dc8..00000000 --- a/docs/architecture/ARCHITECTURE.md +++ /dev/null @@ -1,225 +0,0 @@ - - - - -# PanLL Architecture - -PanLL (pronounced "parallel") is a Human-Things Interface (HTI) built with -ReScript + Tauri 2.0. This document describes the major architectural patterns. - -## Three-Panel Layout - -The UI is split into three persistent panels: - -| Panel | Role | Content | -|-------|------|---------| -| **Panel-L** (Symbolic Mass) | Constraints, formal specs, proofs | Type rules, ECHIDNA verification, Anti-Crash gate | -| **Panel-N** (Neural Stream) | AI reasoning, OODA loop | Inference manifold, confidence display, agent monologue | -| **Panel-W** (World/Barycentre) | Results, dashboards, live data | VeriSimDB results, security findings, task outputs | - -Overlay panels (41 total) appear one at a time on top of the core three. -The Panel Switcher navigation bar controls which overlay is active. At most -one overlay is visible; setting `activePanel` to `None` shows only the core -panels. - -## TEA (The Elm Architecture) - -PanLL uses a custom TEA implementation in `src/tea/`. This is **not** -rescript-tea@0.16.0 — the upstream package is incompatible with the panel -architecture, so PanLL maintains its own fork. - -### TEA Modules - -| Module | Path | Purpose | -|--------|------|---------| -| `Tea_App` | `src/tea/Tea_App.res` | Application lifecycle — init, update, view, subscriptions | -| `Tea_Cmd` | `src/tea/Tea_Cmd.res` | Side-effect commands — `Tea_Cmd.call(callbacks => ...)` | -| `Tea_Sub` | `src/tea/Tea_Sub.res` | Subscriptions — timers, event listeners | -| `Tea_Html` | `src/tea/Tea_Html.res` | Virtual DOM element constructors | -| `Tea_Vdom` | `src/tea/Tea_Vdom.res` | Virtual DOM diffing and patching | -| `Tea_Render` | `src/tea/Tea_Render.res` | DOM rendering pipeline | -| `Tea_Time` | `src/tea/Tea_Time.res` | Time-based subscriptions | -| `Tea_Animationframe` | `src/tea/Tea_Animationframe.res` | requestAnimationFrame subscriptions | -| `Tea` | `src/tea/Tea.res` | Re-export module | - -### The Cycle - -``` - ┌──────────┐ - │ Model │ (immutable state record) - └────┬─────┘ - │ - ┌──────────▼──────────┐ - │ View(model) │ (model → Tea_Html virtual DOM) - └──────────┬──────────┘ - │ - ┌──────────▼──────────┐ - │ DOM Events │ (user clicks, key presses) - └──────────┬──────────┘ - │ - ┌──────────▼──────────┐ - │ Msg dispatched │ (variant type — exhaustive match) - └──────────┬──────────┘ - │ - ┌──────────▼──────────┐ - │ Update(model,msg) │ (returns (model, Cmd)) - └──────────┬──────────┘ - │ - ┌────▼─────┐ - │ Model' │ (new state → re-render) - └──────────┘ -``` - -Key conventions: -- Commands use `Tea_Cmd.call(callbacks => ...)`, never `Tea_Cmd.promise` -- List conversion: `->List.fromArray` not `->Array.toList` -- Style attributes: `Attrs.style("property", "value")` (two string args) -- No JSX — all panels use `Tea_Html` element constructors -- `Events.onCheck` does not exist — use `Events.onClick` - -## Engine Pattern - -Every panel follows a consistent four-file pattern: - -``` -src/ -├── model/XxxModel.res # Types — state records, msg variants -├── core/XxxEngine.res # Pure computation — no side effects -├── commands/XxxCmd.res # Tauri invoke calls — side effects -└── components/Xxx.res # View — Tea_Html rendering -``` - -| Layer | Responsibility | Testable? | -|-------|---------------|-----------| -| **Model** (`XxxModel.res`) | Type definitions — state, messages, sub-models | N/A (types only) | -| **Engine** (`XxxEngine.res`) | Pure functions — state transitions, filtering, formatting | Yes (Deno tests) | -| **Cmd** (`XxxCmd.res`) | Side effects — `Tauri.invoke`, `Tea_Cmd.call` | No (requires Tauri runtime) | -| **View** (`Xxx.res`) | `Tea_Html` rendering — maps model to virtual DOM | Integration tests | - -There are 47 engine files in `src/core/`. Tests import the compiled `.res.js` -output from engines and exercise pure functions without needing a browser or -Tauri runtime. - -## Clade System - -Every panel belongs to a **clade** — a taxonomy entry defined in an A2ML file -under `panel-clades/clades/`. Clades provide: - -- **Trait inheritance**: panels inherit capabilities from parent clades -- **Kind filtering**: the Clade Browser can filter panels by kind -- **Capability queries**: `PanelRegistry.panelHasTrait(id, clades, getter)` - -There are 41 clade definitions. The `CladeBrowserEngine` resolves trait -inheritance chains. The Rust `clade_scanner` module reads `.a2ml` files from -disk and returns them to the frontend. - -## BoJ Gateway - -The Bundle of Joy (BoJ) server is PanLL's primary service gateway. When -`bojRouting` is enabled, panels route through BoJ cartridges instead of -direct HTTP calls: - -| Protocol | Cartridge | Panels Using | -|----------|-----------|-------------| -| LSP (Language Server Protocol) | `lsp-mcp` | Editor Bridge | -| DAP (Debug Adapter Protocol) | `dap-mcp` | VM Inspector | -| BSP (Build Server Protocol) | `bsp-mcp` | Build Dashboard | -| Database queries | `database-mcp` | Databases, Panel-W | - -BoJ exposes 17 cartridges total. The `boj/` Rust module proxies requests to -the BoJ server at `BOJ_URL` (default `http://localhost:7700/api/v1`). The -Umoja federation protocol enables peer-to-peer cartridge sharing between BoJ -instances. - -## A2ML / K9 Integration Layer - -**A2ML** (AI Markup Language) is the manifest format for AI agents. PanLL -reads `0-AI-MANIFEST.a2ml` files to understand repository structure and -configure panels automatically. - -**K9** (Kennel) manages contractile configurations — validation rules and -layout constraints stored in `.a2ml` files. The K9 engine: -- Loads contractiles from `Trustfile.a2ml` -- Validates panel configurations against Yard contracts -- Applies layout constraints (isolation tiers, panel grouping) - -The `a2ml/` and `k9/` Rust modules handle file I/O; the `A2mlEngine` and -`K9Engine` ReScript modules handle pure logic. - -## Coprocessor Engine (Phase 1-3) - -The coprocessor system offloads compute-intensive tasks: - -| Phase | Layer | Purpose | -|-------|-------|---------| -| **Phase 1** | Control plane | CPU monitoring, task queuing, device discovery | -| **Phase 2** | Data plane (Zig FFI) | Direct FFI calls to compute engines (Axiom.jl, etc.) | -| **Phase 3** | Smart routing | Automatic dispatch: local (CPU<80%) / remote (neural) / BoJ (fallback) | - -The `coprocessor/` Rust module exposes 8 commands for device discovery, -benchmarking, FFI loading, and smart dispatch. When local FFI is unavailable, -tasks fall back to BoJ cartridge invocation. - -## Cognitive Governance - -Six ambient systems monitor operator cognitive state: - -| System | Purpose | Mechanism | -|--------|---------|-----------| -| **Vexometer** | Friction monitoring | Tracks cancellations + corrections, decays over 120s | -| **Anti-Crash Gate** | Circuit breaker | Validates neural output before it reaches Panel-W | -| **Orbital Drift Aura** | Stability indicator | Ambient visual cue for system health | -| **Feedback-O-Tron** | Performance reporting | Community-driven constraint suggestions | -| **Information Humidity** | UI density adaptation | High/Medium/Low modes adjust information density | -| **Dark Start** | Entry point | Architecture manifold bootstrapping | - -These are not standalone panels — they operate as always-present subsystems -that influence the entire UI surface. - -## Backend Architecture - -``` -┌─────────────────────────┐ -│ ReScript Frontend │ 245 .res files, compiled to JS -│ (TEA cycle) │ -└────────┬────────────────┘ - │ Tauri invoke() -┌────────▼────────────────┐ -│ Rust Backend (Tauri) │ 77 .rs files, 246 commands -│ src-tauri/src/ │ 26 modules + main.rs -└────────┬────────────────┘ - │ HTTP / WebSocket / CLI -┌────────▼────────────────┐ -│ External Services │ -│ - BoJ Server (:7700) │ -│ - TypeLL Server (:7800)│ -│ - ECHIDNA (V-lang) │ -│ - Phoenix (:4000) │ -│ - Cloudflare API │ -│ - panic-attack CLI │ -│ - protocol-squisher CLI│ -│ - my-lang CLI │ -└─────────────────────────┘ -``` - -## Directory Structure - -``` -panll/ -├── src/ # ReScript frontend -│ ├── tea/ # Custom TEA implementation (8 modules) -│ ├── model/ # Type definitions (XxxModel.res) -│ ├── core/ # Pure engines (XxxEngine.res) — 47 files -│ ├── commands/ # Tauri invoke wrappers (XxxCmd.res) -│ ├── components/ # View functions (Xxx.res) -│ └── modules/ # Cross-cutting modules (PanelRegistry, etc.) -├── src-tauri/src/ # Rust backend -│ ├── main.rs # Entry point, invoke_handler registration -│ └── /commands.rs # Per-module Tauri commands -├── tests/ # Deno test files (45 files) -├── panel-clades/clades/ # A2ML clade definitions (41 clades) -├── public/ # Static assets, index.html -├── docs/ # Documentation -├── beam/panll_beam/ # Optional Elixir/BEAM middleware -└── deno.json # Task runner and import map -``` diff --git a/docs/architecture/PANEL-INVENTORY.adoc b/docs/architecture/PANEL-INVENTORY.adoc new file mode 100644 index 00000000..42f7cc1c --- /dev/null +++ b/docs/architecture/PANEL-INVENTORY.adoc @@ -0,0 +1,412 @@ +== Panel Inventory + +PanLL has 79 panel entries across 11 categories. The three core panels +(L, N, W) are always visible; overlay panels appear one at a time on top +of them. The 28 game dev panels (added 2026-03-14) exist as clade +definitions; ReScript Model/Update/View/Cmd modules are pending +implementation. K9 Manager, Contractile Manager, and Wiring Inspector +added 2026-03-15. + +=== Core Panels (3) + +These panels form the permanent three-panel layout and are always +rendered. + +[width="100%",cols="24%,33%,43%",options="header",] +|=== +|Panel |Category |Description +|Panel-L (Symbolic Mass) |Core |Constraints, formal specs, type rules, +proofs + +|Panel-N (Neural Stream) |Core |AI reasoning, ECHIDNA confidence, OODA +loop + +|Panel-W (World/Barycentre) |Core |Results, dashboards, VeriSimDB, live +data +|=== + +=== Overlay Panels (14) + +Full-screen overlays activated via the panel bar. At most one is active +at a time. + +[width="100%",cols="13%,14%,11%,20%,22%,20%",options="header",] +|=== +|Panel |panelId |Short |Source Files |Rust Backend |Description +|CloudGuard |`+PanelCloudGuard+` |CG |CloudGuardEngine, CloudGuardCmd, +CloudGuardModel, CloudGuard |`+cloudguard/+` (14 commands) |Cloudflare +domain security management + +|VAB |`+PanelVab+` |VAB |VabEngine, VabModel, Vab |None (local catalog) +|Verified Assembly Building — server component composer + +|Farm |`+PanelFarm+` |Farm |FarmEngine, FarmModel, Farm |`+farm/+` (3 +commands) |Repository admin registry and maintenance hub + +|Fleet |`+PanelFleet+` |Fleet |FleetEngine, FleetModel, Fleet |None +(external Axum API) |Gitbot fleet orchestration and dispatch + +|Hypatia |`+PanelHypatia+` |Hyp |HypatiaEngine, HypatiaModel, Hypatia +|None (external Elixir API) |Neurosymbolic CI/CD intelligence + +|Reposystem |`+PanelReposystem+` |RSR |ReposystemEngine, +ReposystemModel, Reposystem |None (filesystem scanning) |RSR compliance +and template management + +|Aerie |`+PanelAerie+` |Net |AerieEngine, AerieModel, Aerie +|`+overlay/+` (21 commands) |Network diagnostics, BGP forensics, overlay +networks + +|Interfaces |`+PanelInterfaces+` |FFI |InterfacesEngine, +InterfacesModel, Interfaces |None (filesystem scanning) |Language +bridges, ABI/FFI inventory + +|Playgrounds |`+PanelPlaygrounds+` |Play |PlaygroundsEngine, +PlaygroundsModel, Playgrounds |None (NQC proxy) |Code sandbox, NQC +console, tutorials + +|Palimpsest Plaza |`+PanelPlaza+` |PMPL |PlazaEngine, PlazaModel, Plaza +|`+plaza/+` (3 commands) |PMPL license adoption, compliance, governance + +|Minter |`+PanelMinter+` |Mint |MinterEngine, MinterModel, Minter +|`+minter/+` (2 commands) |Panel creation wizard — generate accessible +panel modules + +|Protocol-Squisher |`+PanelProtocolSquisher+` |Squisher +|ProtocolSquisherEngine, ProtocolSquisherModel, ProtocolSquisher +|main.rs (3 commands) |13-format schema analysis, compatibility +comparison + +|My-Lang |`+PanelMyLang+` |My-Lang |MyLangEngine, MyLangModel, MyLang +|main.rs (5 commands) |AI-native language workbench — 4 dialects, REPL, +compiler + +|BoJ |`+PanelBoj+` |BoJ |BojEngine, BojModel, Boj |`+boj/+` (8 commands) +|Bundle of Joy — 17-cartridge server, Umoja federation +|=== + +=== IDApTIK eNSAID Panels (11) + +Panels specific to the IDApTIK game engine development environment. + +[width="100%",cols="13%,14%,11%,20%,22%,20%",options="header",] +|=== +|Panel |panelId |Short |Source Files |Rust Backend |Description +|Valence Shell |`+PanelValenceShell+` |VS |ValenceShellEngine, +ValenceShellModel, ValenceShell |`+valence_shell/+` (12 commands) +|Embedded terminal, session recording, checkpoints + +|Game Preview |`+PanelGamePreview+` |Game |GamePreviewEngine, +GamePreviewModel, GamePreview |`+game_preview/+` (8 commands) |Live +IDApTIK preview, hot-reload, frame stepping + +|VM Inspector |`+PanelVmInspector+` |VM |VmInspectorEngine, +VmInspectorModel, VmInspector |`+vm_inspector/+` (7 commands) +|Reversible VM debugger — stack, memory, stepping + +|Network Topology |`+PanelNetworkTopology+` |Topo +|NetworkTopologyEngine, NetworkTopologyModel, NetworkTopology +|`+network_topology/+` (4 commands) |Force-directed graph of in-game +network + +|Level Architect |`+PanelLevelArchitect+` |Lvl |LevelArchitectEngine, +LevelArchitectModel, LevelArchitect |`+level_architect/+` (5 commands) +|Visual level design, device placement, validation + +|Coprocessors |`+PanelCoprocessors+` |CoPr |CoprocessorsEngine, +CoprocessorsModel, Coprocessors |`+coprocessor/+` (8 commands) |Monitor +10 coprocessor backends, heatmap, health + +|Multiplayer Monitor |`+PanelMultiplayerMonitor+` |MP +|MultiplayerMonitorEngine, MultiplayerMonitorModel, MultiplayerMonitor +|`+multiplayer_monitor/+` (6 commands) |Phoenix sync server — WebSocket, +Lamport clocks + +|DLC Workshop |`+PanelDlcWorkshop+` |DLC |DlcWorkshopEngine, +DlcWorkshopModel, DlcWorkshop |`+dlc_workshop/+` (8 commands) |Puzzle +pack creation, VM composer, asset bundling + +|Editor Bridge |`+PanelEditorBridge+` |EB |EditorBridgeEngine, +EditorBridgeModel, EditorBridge |None (LSP via BoJ) |Federate with +external editors — LSP diagnostics + +|Build Dashboard |`+PanelBuildDashboard+` |Bld |BuildDashboardEngine, +BuildDashboardModel, BuildDashboard |None (BSP via BoJ) |Monitor builds, +tests, compilation status + +|Release Manager |`+PanelReleaseManager+` |Rel |ReleaseManagerEngine, +ReleaseManagerModel, ReleaseManager |`+release_manager/+` (5 commands) +|Versioning, changelog, artifact signing, distribution +|=== + +=== Cross-Cutting Services (4) + +These are not standalone panels but provide capabilities that span +multiple panels. + +[width="100%",cols="13%,14%,11%,20%,22%,20%",options="header",] +|=== +|Panel |panelId |Short |Source Files |Rust Backend |Description +|TypeLL |`+PanelTypeLL+` |TypeLL |TypeLLEngine, TypeLLModel, TypeLL +|`+typell/+` (7 commands) |Verification kernel — dependent, linear, +session types + +|7-Tentacles |`+PanelTentacles+` |Tentacles |TentaclesEngine, +TentaclesModel, Tentacles |None (ECHIDNA FFI) |Multi-agent +orchestration, OODA reasoning, cephalopod staging + +|A2ML/K9 |(via PanelCladeBrowser) |— |A2mlEngine, K9Engine |`+a2ml/+` +(3) + `+k9/+` (3) |Manifest parsing, contractile validation, layout + +|Coprocessor Engine |`+PanelCoprocessors+` |CoPr |CoprocessorsEngine +|`+coprocessor/+` (8 commands) |Control + data + smart routing (Phase +1-3) +|=== + +=== Infrastructure (5) + +Ambient infrastructure panels always present or accessed via the panel +bar. + +[width="100%",cols="13%,14%,11%,20%,22%,20%",options="header",] +|=== +|Panel |panelId |Short |Source Files |Rust Backend |Description +|Panel Switcher |(built-in) |— |PanelSwitcherModel, PanelRegistry, +PanelBar |None |Unified navigation bar + +|Provisioner |`+PanelProvisioner+` |Prov |ProvisionerEngine, +ProvisionerModel, Provisioner |None (Stapeln/Podman) |Portfolios, +configuration, isolation tiers + +|Code Provenance |`+PanelVoiceTag+` |MRI |VoiceTagEngine, VoiceTagModel, +VoiceTag |`+voicetag/+` (4 commands) |Trust surface, 4 palettes, +.mri.json sidecars + +|Filesystem Watcher |(built-in) |— |WatcherModel |`+watcher/+` (5 +commands) |Rust notify + ReScript event stream + +|Clade Browser |`+PanelCladeBrowser+` |Clade |CladeBrowserEngine, +CladeBrowserModel, CladeBrowser |`+clade_scanner/+` (1 command) |41 +clades, inheritance engine, taxonomy +|=== + +=== Cognitive Governance (6) + +Ambient cognitive ergonomics — always present, no dedicated panel IDs. + +[width="100%",cols="13%,16%,23%,25%,23%",options="header",] +|=== +|Panel |panelId |Source Files |Rust Backend |Description +|Vexometer |(built-in) |VexometerModel, Vexometer |main.rs +(`+record_vexation_event+`, `+get_vexation_index+`) |Real-time friction +monitoring + +|Anti-Crash Gate |(built-in) |AntiCrashModel |main.rs +(`+validate_inference+`) |Neural token gating, circuit breaker + +|Orbital Drift Aura |(built-in) |OrbitalDriftModel |None |Ambient +stability indicator + +|Feedback-O-Tron |(built-in) |FeedbackOTronModel |main.rs +(`+submit_feedback+`) |Community-driven performance reporting + +|Information Humidity |(built-in) |HumidityModel |None |UI density +adaptation (High/Medium/Low) + +|Dark Start |(built-in) |DarkStartModel |None |Architecture manifold +entry point +|=== + +=== Additional Utility Panels + +[width="100%",cols="13%,14%,11%,20%,22%,20%",options="header",] +|=== +|Panel |panelId |Short |Source Files |Rust Backend |Description +|Databases |`+PanelDatabases+` |DB |— |main.rs (8 verisim + 10 echidna) +|VeriSimDB, QuandleDB, LithoGlyph management + +|AI |`+PanelAi+` |AI |AiEngine, AiModel |`+ai/+` (8 commands) +|Multi-provider neural interface + +|Repo Loader |`+PanelRepoLoader+` |Repo |RepoLoaderEngine +|`+repoloader/+` (4 commands) |Repository scanner and panel +configuration + +|Workspace |`+PanelWorkspace+` |WS |WorkspaceEngine, WorkspaceModel +|`+workspace/+` (7 commands) |Arrangements, groups, sessions, modes + +|Capture |`+PanelCapture+` |Cap |CaptureEngine, CaptureModel +|`+capture/+` (5 commands) |Screenshots, recordings, demos + +|Security |`+PanelSecurity+` |Sec |SecurityEngine, SecurityModel +|`+security/+` (5 commands) |Redaction, vault, 2FA, Trustfile +enforcement + +|Migration |`+PanelMigration+` |Mig |MigrationEngine, MigrationModel +|None (panic-attack CLI) |ReScript Migration Observatory + +|panic-attack |`+PanelPanicAttack+` |PA |PanicAttackModel |main.rs (4 +commands) |Stress testing, bug signature detection + +|Mass Panic |`+PanelMassPanic+` |MP |MassPanicModel |main.rs (via +panic-attack) |Batch scanning — assemblyline + BLAKE3 + +|TSDM |`+PanelTsdm+` |TSD |TsdmModel |None |Triaxial Software +Development Methodology + +|Automation Router |`+PanelAutomationRouter+` |Auto +|AutomationRouterEngine |None (ENSAID_CONFIG reading) |Cross-panel +workflow orchestration + +|Observability |(via governance) |— |ObservabilityEngine +|`+observability/+` (3 commands) |SARIF export, OpenTelemetry traces + +|Umoja |(via BoJ) |— |— |`+umoja/+` (5 commands) |Federation gossip +protocol peer management +|=== + +=== Game Dev — Testing (10) + +Panels for test orchestration, profiling, compatibility, and balance +analysis. *Status:* Clade definitions only (a2ml manifests). ReScript +implementation pending. + +[width="100%",cols="19%,21%,16%,14%,30%",options="header",] +|=== +|Panel |panelId |Short |Kind |Description +|Unit Test Runner |`+PanelUnitTestRunner+` |UTR |Scanner |Execute unit +test suites, pass/fail tree, coverage heatmap + +|Functional Tester |`+PanelFunctionalTester+` |FT |Scanner +|Scenario-based functional test orchestration, screenshots + +|Regression Guard |`+PanelRegressionGuard+` |RG |Scanner |Baseline +comparison, drift detection, blame analysis + +|Performance Profiler |`+PanelPerformanceProfiler+` |Perf |Inspector +|CPU flame graphs, memory tracking, frame timing + +|Load Tester |`+PanelLoadTester+` |Load |Scanner |Synthetic load +generation, latency percentiles, throughput + +|Soak Monitor |`+PanelSoakMonitor+` |Soak |Inspector |Long-running +stability, memory leaks, resource trends + +|Compatibility Matrix |`+PanelCompatibilityMatrix+` |Compat |Viewer +|Cross-platform/version test matrix, colour-coded grid + +|Exploratory Workbench |`+PanelExploratoryWorkbench+` |Explore |Builder +|Free-form manual testing, session notes, bug tagging + +|Beta Feedback Hub |`+PanelBetaFeedbackHub+` |Beta |Viewer +|Player/tester feedback collection, sentiment, triage + +|Balance Analyser |`+PanelBalanceAnalyser+` |Balance |Inspector +|Difficulty curves, win/loss tracking, resource economy +|=== + +=== Game Dev — Bridge (8) + +Panels bridging PanLL to external systems, type systems, protocols, and +runtimes. *Status:* Clade definitions only (a2ml manifests). ReScript +implementation pending. + +[width="100%",cols="19%,21%,16%,14%,30%",options="header",] +|=== +|Panel |panelId |Short |Kind |Description +|Typing Bridge |`+PanelTypingBridge+` |TyBr |Bridge |Bridge TypeLL to +Idris2, Rust, ReScript, Gleam type systems + +|Neurosym Bridge |`+PanelNeurosymBridge+` |NeSy |Bridge |Neural-symbolic +translation, confidence gating, proof-guided inference + +|Agentic Bridge |`+PanelAgenticBridge+` |Agent |Bridge |External AI +agent dispatch (MCP, Claude Code, ECHIDNA) + +|Automation Bridge |`+PanelAutomationBridge+` |CI |Bridge |CI/CD +pipeline trigger, monitoring, artifact collection + +|Database Bridge |`+PanelDatabaseBridge+` |DBBr |Bridge +|VeriSimDB/QuandleDB query proxy, schema inspection + +|Protocol Bridge |`+PanelProtocolBridge+` |Proto |Bridge +|MCP/LSP/DAP/BSP/gRPC message translation and inspection + +|Proofs Bridge |`+PanelProofsBridge+` |Proof |Bridge |Formal +verification (Idris2, ECHIDNA, Lean4) proof submission + +|Scripting Bridge |`+PanelScriptingBridge+` |Script |Bridge +|Deno/Julia/Elixir/Lua snippet execution, sandbox management +|=== + +=== Game Dev — Game-Specific (6) + +Panels for IDApTIK game content creation, AI tuning, and playtesting. +*Status:* Clade definitions only (a2ml manifests). ReScript +implementation pending. + +[width="100%",cols="19%,21%,16%,14%,30%",options="header",] +|=== +|Panel |panelId |Short |Kind |Description +|Generator Mode |`+PanelGeneratorMode+` |Gen |Builder |Procedural +level/puzzle/topology generation with constraint satisfaction + +|Architect Mode |`+PanelArchitectMode+` |Arch |Builder |High-level +system design, dependency graphs, ADR management + +|Guard AI Tuner |`+PanelGuardAiTuner+` |GAI |Builder |Tune guard AI +patrol patterns, detection, escalation, difficulty + +|Device Network Designer |`+PanelDeviceNetworkDesigner+` |NetDes +|Builder |Visual in-game network designer, drag-and-drop, topology +validation + +|Asset Manager |`+PanelAssetManager+` |Asset |Loader |Game asset +inventory, import pipeline, unused detection + +|Playtest Recorder |`+PanelPlaytestRecorder+` |Play |Inspector +|Record/replay play sessions, input capture, decision trees +|=== + +=== Game Dev — Team (4) + +Panels for collaborative development workflows. *Status:* Clade +definitions only (a2ml manifests). ReScript implementation pending. + +[width="100%",cols="19%,21%,16%,14%,30%",options="header",] +|=== +|Panel |panelId |Short |Kind |Description +|Code Review |`+PanelCodeReview+` |Review |Viewer |In-panel diff views, +inline comments, approval workflow + +|Merge Coordinator |`+PanelMergeCoordinator+` |Merge |Directive |Branch +management, conflict resolution, merge queues + +|Team Dashboard |`+PanelTeamDashboard+` |Team |Viewer |Commit velocity, +review throughput, build health overview + +|Debugging Workbench |`+PanelDebuggingWorkbench+` |Debug |Inspector +|DAP-backed breakpoints, watch expressions, multi-runtime +|=== + +=== Governance & Contracts (3) + +Panels for contractile enforcement, K9 security validation, and wiring +integrity. *Status:* Implemented 2026-03-15 with full ReScript +components. + +[width="100%",cols="13%,14%,11%,20%,22%,20%",options="header",] +|=== +|Panel |panelId |Short |Source Files |Rust Backend |Description +|K9 Manager |`+PanelK9Manager+` |K9 |K9Model, K9Manager |via `+k9/+` +commands |Security level badges (Kennel/Yard/Hunt), file validation, +Load/Validate/Apply + +|Contractile Manager |`+PanelContractileManager+` |CTR +|ContractileManager |via contractiles |11 built-in contractiles, +colour-coded status, elasticity bars, vexation index + +|Wiring Inspector |`+PanelWiringInspector+` |Wire |WiringInspectorModel, +WiringInspector |None |Phase 5 Constraint Audit Dashboard, 77 panel +contracts, PCC verification +|=== diff --git a/docs/architecture/PANEL-INVENTORY.md b/docs/architecture/PANEL-INVENTORY.md deleted file mode 100644 index 9c17f2a1..00000000 --- a/docs/architecture/PANEL-INVENTORY.md +++ /dev/null @@ -1,185 +0,0 @@ - - - - -# Panel Inventory - -PanLL has 79 panel entries across 11 categories. The three core panels (L, N, W) -are always visible; overlay panels appear one at a time on top of them. -The 28 game dev panels (added 2026-03-14) exist as clade definitions; ReScript -Model/Update/View/Cmd modules are pending implementation. -K9 Manager, Contractile Manager, and Wiring Inspector added 2026-03-15. - -## Core Panels (3) - -These panels form the permanent three-panel layout and are always rendered. - -| Panel | Category | Description | -|-------|----------|-------------| -| Panel-L (Symbolic Mass) | Core | Constraints, formal specs, type rules, proofs | -| Panel-N (Neural Stream) | Core | AI reasoning, ECHIDNA confidence, OODA loop | -| Panel-W (World/Barycentre) | Core | Results, dashboards, VeriSimDB, live data | - -## Overlay Panels (14) - -Full-screen overlays activated via the panel bar. At most one is active at a time. - -| Panel | panelId | Short | Source Files | Rust Backend | Description | -|-------|---------|-------|-------------|--------------|-------------| -| CloudGuard | `PanelCloudGuard` | CG | CloudGuardEngine, CloudGuardCmd, CloudGuardModel, CloudGuard | `cloudguard/` (14 commands) | Cloudflare domain security management | -| VAB | `PanelVab` | VAB | VabEngine, VabModel, Vab | None (local catalog) | Verified Assembly Building — server component composer | -| Farm | `PanelFarm` | Farm | FarmEngine, FarmModel, Farm | `farm/` (3 commands) | Repository admin registry and maintenance hub | -| Fleet | `PanelFleet` | Fleet | FleetEngine, FleetModel, Fleet | None (external Axum API) | Gitbot fleet orchestration and dispatch | -| Hypatia | `PanelHypatia` | Hyp | HypatiaEngine, HypatiaModel, Hypatia | None (external Elixir API) | Neurosymbolic CI/CD intelligence | -| Reposystem | `PanelReposystem` | RSR | ReposystemEngine, ReposystemModel, Reposystem | None (filesystem scanning) | RSR compliance and template management | -| Aerie | `PanelAerie` | Net | AerieEngine, AerieModel, Aerie | `overlay/` (21 commands) | Network diagnostics, BGP forensics, overlay networks | -| Interfaces | `PanelInterfaces` | FFI | InterfacesEngine, InterfacesModel, Interfaces | None (filesystem scanning) | Language bridges, ABI/FFI inventory | -| Playgrounds | `PanelPlaygrounds` | Play | PlaygroundsEngine, PlaygroundsModel, Playgrounds | None (NQC proxy) | Code sandbox, NQC console, tutorials | -| Palimpsest Plaza | `PanelPlaza` | PMPL | PlazaEngine, PlazaModel, Plaza | `plaza/` (3 commands) | PMPL license adoption, compliance, governance | -| Minter | `PanelMinter` | Mint | MinterEngine, MinterModel, Minter | `minter/` (2 commands) | Panel creation wizard — generate accessible panel modules | -| Protocol-Squisher | `PanelProtocolSquisher` | Squisher | ProtocolSquisherEngine, ProtocolSquisherModel, ProtocolSquisher | main.rs (3 commands) | 13-format schema analysis, compatibility comparison | -| My-Lang | `PanelMyLang` | My-Lang | MyLangEngine, MyLangModel, MyLang | main.rs (5 commands) | AI-native language workbench — 4 dialects, REPL, compiler | -| BoJ | `PanelBoj` | BoJ | BojEngine, BojModel, Boj | `boj/` (8 commands) | Bundle of Joy — 17-cartridge server, Umoja federation | - -## IDApTIK eNSAID Panels (11) - -Panels specific to the IDApTIK game engine development environment. - -| Panel | panelId | Short | Source Files | Rust Backend | Description | -|-------|---------|-------|-------------|--------------|-------------| -| Valence Shell | `PanelValenceShell` | VS | ValenceShellEngine, ValenceShellModel, ValenceShell | `valence_shell/` (12 commands) | Embedded terminal, session recording, checkpoints | -| Game Preview | `PanelGamePreview` | Game | GamePreviewEngine, GamePreviewModel, GamePreview | `game_preview/` (8 commands) | Live IDApTIK preview, hot-reload, frame stepping | -| VM Inspector | `PanelVmInspector` | VM | VmInspectorEngine, VmInspectorModel, VmInspector | `vm_inspector/` (7 commands) | Reversible VM debugger — stack, memory, stepping | -| Network Topology | `PanelNetworkTopology` | Topo | NetworkTopologyEngine, NetworkTopologyModel, NetworkTopology | `network_topology/` (4 commands) | Force-directed graph of in-game network | -| Level Architect | `PanelLevelArchitect` | Lvl | LevelArchitectEngine, LevelArchitectModel, LevelArchitect | `level_architect/` (5 commands) | Visual level design, device placement, validation | -| Coprocessors | `PanelCoprocessors` | CoPr | CoprocessorsEngine, CoprocessorsModel, Coprocessors | `coprocessor/` (8 commands) | Monitor 10 coprocessor backends, heatmap, health | -| Multiplayer Monitor | `PanelMultiplayerMonitor` | MP | MultiplayerMonitorEngine, MultiplayerMonitorModel, MultiplayerMonitor | `multiplayer_monitor/` (6 commands) | Phoenix sync server — WebSocket, Lamport clocks | -| DLC Workshop | `PanelDlcWorkshop` | DLC | DlcWorkshopEngine, DlcWorkshopModel, DlcWorkshop | `dlc_workshop/` (8 commands) | Puzzle pack creation, VM composer, asset bundling | -| Editor Bridge | `PanelEditorBridge` | EB | EditorBridgeEngine, EditorBridgeModel, EditorBridge | None (LSP via BoJ) | Federate with external editors — LSP diagnostics | -| Build Dashboard | `PanelBuildDashboard` | Bld | BuildDashboardEngine, BuildDashboardModel, BuildDashboard | None (BSP via BoJ) | Monitor builds, tests, compilation status | -| Release Manager | `PanelReleaseManager` | Rel | ReleaseManagerEngine, ReleaseManagerModel, ReleaseManager | `release_manager/` (5 commands) | Versioning, changelog, artifact signing, distribution | - -## Cross-Cutting Services (4) - -These are not standalone panels but provide capabilities that span multiple panels. - -| Panel | panelId | Short | Source Files | Rust Backend | Description | -|-------|---------|-------|-------------|--------------|-------------| -| TypeLL | `PanelTypeLL` | TypeLL | TypeLLEngine, TypeLLModel, TypeLL | `typell/` (7 commands) | Verification kernel — dependent, linear, session types | -| 7-Tentacles | `PanelTentacles` | Tentacles | TentaclesEngine, TentaclesModel, Tentacles | None (ECHIDNA FFI) | Multi-agent orchestration, OODA reasoning, cephalopod staging | -| A2ML/K9 | (via PanelCladeBrowser) | — | A2mlEngine, K9Engine | `a2ml/` (3) + `k9/` (3) | Manifest parsing, contractile validation, layout | -| Coprocessor Engine | `PanelCoprocessors` | CoPr | CoprocessorsEngine | `coprocessor/` (8 commands) | Control + data + smart routing (Phase 1-3) | - -## Infrastructure (5) - -Ambient infrastructure panels always present or accessed via the panel bar. - -| Panel | panelId | Short | Source Files | Rust Backend | Description | -|-------|---------|-------|-------------|--------------|-------------| -| Panel Switcher | (built-in) | — | PanelSwitcherModel, PanelRegistry, PanelBar | None | Unified navigation bar | -| Provisioner | `PanelProvisioner` | Prov | ProvisionerEngine, ProvisionerModel, Provisioner | None (Stapeln/Podman) | Portfolios, configuration, isolation tiers | -| Code Provenance | `PanelVoiceTag` | MRI | VoiceTagEngine, VoiceTagModel, VoiceTag | `voicetag/` (4 commands) | Trust surface, 4 palettes, .mri.json sidecars | -| Filesystem Watcher | (built-in) | — | WatcherModel | `watcher/` (5 commands) | Rust notify + ReScript event stream | -| Clade Browser | `PanelCladeBrowser` | Clade | CladeBrowserEngine, CladeBrowserModel, CladeBrowser | `clade_scanner/` (1 command) | 41 clades, inheritance engine, taxonomy | - -## Cognitive Governance (6) - -Ambient cognitive ergonomics — always present, no dedicated panel IDs. - -| Panel | panelId | Source Files | Rust Backend | Description | -|-------|---------|-------------|--------------|-------------| -| Vexometer | (built-in) | VexometerModel, Vexometer | main.rs (`record_vexation_event`, `get_vexation_index`) | Real-time friction monitoring | -| Anti-Crash Gate | (built-in) | AntiCrashModel | main.rs (`validate_inference`) | Neural token gating, circuit breaker | -| Orbital Drift Aura | (built-in) | OrbitalDriftModel | None | Ambient stability indicator | -| Feedback-O-Tron | (built-in) | FeedbackOTronModel | main.rs (`submit_feedback`) | Community-driven performance reporting | -| Information Humidity | (built-in) | HumidityModel | None | UI density adaptation (High/Medium/Low) | -| Dark Start | (built-in) | DarkStartModel | None | Architecture manifold entry point | - -## Additional Utility Panels - -| Panel | panelId | Short | Source Files | Rust Backend | Description | -|-------|---------|-------|-------------|--------------|-------------| -| Databases | `PanelDatabases` | DB | — | main.rs (8 verisim + 10 echidna) | VeriSimDB, QuandleDB, LithoGlyph management | -| AI | `PanelAi` | AI | AiEngine, AiModel | `ai/` (8 commands) | Multi-provider neural interface | -| Repo Loader | `PanelRepoLoader` | Repo | RepoLoaderEngine | `repoloader/` (4 commands) | Repository scanner and panel configuration | -| Workspace | `PanelWorkspace` | WS | WorkspaceEngine, WorkspaceModel | `workspace/` (7 commands) | Arrangements, groups, sessions, modes | -| Capture | `PanelCapture` | Cap | CaptureEngine, CaptureModel | `capture/` (5 commands) | Screenshots, recordings, demos | -| Security | `PanelSecurity` | Sec | SecurityEngine, SecurityModel | `security/` (5 commands) | Redaction, vault, 2FA, Trustfile enforcement | -| Migration | `PanelMigration` | Mig | MigrationEngine, MigrationModel | None (panic-attack CLI) | ReScript Migration Observatory | -| panic-attack | `PanelPanicAttack` | PA | PanicAttackModel | main.rs (4 commands) | Stress testing, bug signature detection | -| Mass Panic | `PanelMassPanic` | MP | MassPanicModel | main.rs (via panic-attack) | Batch scanning — assemblyline + BLAKE3 | -| TSDM | `PanelTsdm` | TSD | TsdmModel | None | Triaxial Software Development Methodology | -| Automation Router | `PanelAutomationRouter` | Auto | AutomationRouterEngine | None (ENSAID_CONFIG reading) | Cross-panel workflow orchestration | -| Observability | (via governance) | — | ObservabilityEngine | `observability/` (3 commands) | SARIF export, OpenTelemetry traces | -| Umoja | (via BoJ) | — | — | `umoja/` (5 commands) | Federation gossip protocol peer management | - -## Game Dev — Testing (10) - -Panels for test orchestration, profiling, compatibility, and balance analysis. -**Status:** Clade definitions only (a2ml manifests). ReScript implementation pending. - -| Panel | panelId | Short | Kind | Description | -|-------|---------|-------|------|-------------| -| Unit Test Runner | `PanelUnitTestRunner` | UTR | Scanner | Execute unit test suites, pass/fail tree, coverage heatmap | -| Functional Tester | `PanelFunctionalTester` | FT | Scanner | Scenario-based functional test orchestration, screenshots | -| Regression Guard | `PanelRegressionGuard` | RG | Scanner | Baseline comparison, drift detection, blame analysis | -| Performance Profiler | `PanelPerformanceProfiler` | Perf | Inspector | CPU flame graphs, memory tracking, frame timing | -| Load Tester | `PanelLoadTester` | Load | Scanner | Synthetic load generation, latency percentiles, throughput | -| Soak Monitor | `PanelSoakMonitor` | Soak | Inspector | Long-running stability, memory leaks, resource trends | -| Compatibility Matrix | `PanelCompatibilityMatrix` | Compat | Viewer | Cross-platform/version test matrix, colour-coded grid | -| Exploratory Workbench | `PanelExploratoryWorkbench` | Explore | Builder | Free-form manual testing, session notes, bug tagging | -| Beta Feedback Hub | `PanelBetaFeedbackHub` | Beta | Viewer | Player/tester feedback collection, sentiment, triage | -| Balance Analyser | `PanelBalanceAnalyser` | Balance | Inspector | Difficulty curves, win/loss tracking, resource economy | - -## Game Dev — Bridge (8) - -Panels bridging PanLL to external systems, type systems, protocols, and runtimes. -**Status:** Clade definitions only (a2ml manifests). ReScript implementation pending. - -| Panel | panelId | Short | Kind | Description | -|-------|---------|-------|------|-------------| -| Typing Bridge | `PanelTypingBridge` | TyBr | Bridge | Bridge TypeLL to Idris2, Rust, ReScript, Gleam type systems | -| Neurosym Bridge | `PanelNeurosymBridge` | NeSy | Bridge | Neural-symbolic translation, confidence gating, proof-guided inference | -| Agentic Bridge | `PanelAgenticBridge` | Agent | Bridge | External AI agent dispatch (MCP, Claude Code, ECHIDNA) | -| Automation Bridge | `PanelAutomationBridge` | CI | Bridge | CI/CD pipeline trigger, monitoring, artifact collection | -| Database Bridge | `PanelDatabaseBridge` | DBBr | Bridge | VeriSimDB/QuandleDB query proxy, schema inspection | -| Protocol Bridge | `PanelProtocolBridge` | Proto | Bridge | MCP/LSP/DAP/BSP/gRPC message translation and inspection | -| Proofs Bridge | `PanelProofsBridge` | Proof | Bridge | Formal verification (Idris2, ECHIDNA, Lean4) proof submission | -| Scripting Bridge | `PanelScriptingBridge` | Script | Bridge | Deno/Julia/Elixir/Lua snippet execution, sandbox management | - -## Game Dev — Game-Specific (6) - -Panels for IDApTIK game content creation, AI tuning, and playtesting. -**Status:** Clade definitions only (a2ml manifests). ReScript implementation pending. - -| Panel | panelId | Short | Kind | Description | -|-------|---------|-------|------|-------------| -| Generator Mode | `PanelGeneratorMode` | Gen | Builder | Procedural level/puzzle/topology generation with constraint satisfaction | -| Architect Mode | `PanelArchitectMode` | Arch | Builder | High-level system design, dependency graphs, ADR management | -| Guard AI Tuner | `PanelGuardAiTuner` | GAI | Builder | Tune guard AI patrol patterns, detection, escalation, difficulty | -| Device Network Designer | `PanelDeviceNetworkDesigner` | NetDes | Builder | Visual in-game network designer, drag-and-drop, topology validation | -| Asset Manager | `PanelAssetManager` | Asset | Loader | Game asset inventory, import pipeline, unused detection | -| Playtest Recorder | `PanelPlaytestRecorder` | Play | Inspector | Record/replay play sessions, input capture, decision trees | - -## Game Dev — Team (4) - -Panels for collaborative development workflows. -**Status:** Clade definitions only (a2ml manifests). ReScript implementation pending. - -| Panel | panelId | Short | Kind | Description | -|-------|---------|-------|------|-------------| -| Code Review | `PanelCodeReview` | Review | Viewer | In-panel diff views, inline comments, approval workflow | -| Merge Coordinator | `PanelMergeCoordinator` | Merge | Directive | Branch management, conflict resolution, merge queues | -| Team Dashboard | `PanelTeamDashboard` | Team | Viewer | Commit velocity, review throughput, build health overview | -| Debugging Workbench | `PanelDebuggingWorkbench` | Debug | Inspector | DAP-backed breakpoints, watch expressions, multi-runtime | - -## Governance & Contracts (3) - -Panels for contractile enforcement, K9 security validation, and wiring integrity. -**Status:** Implemented 2026-03-15 with full ReScript components. - -| Panel | panelId | Short | Source Files | Rust Backend | Description | -|-------|---------|-------|-------------|--------------|-------------| -| K9 Manager | `PanelK9Manager` | K9 | K9Model, K9Manager | via `k9/` commands | Security level badges (Kennel/Yard/Hunt), file validation, Load/Validate/Apply | -| Contractile Manager | `PanelContractileManager` | CTR | ContractileManager | via contractiles | 11 built-in contractiles, colour-coded status, elasticity bars, vexation index | -| Wiring Inspector | `PanelWiringInspector` | Wire | WiringInspectorModel, WiringInspector | None | Phase 5 Constraint Audit Dashboard, 77 panel contracts, PCC verification | diff --git a/docs/architecture/TOPOLOGY.md b/docs/architecture/TOPOLOGY.adoc similarity index 93% rename from docs/architecture/TOPOLOGY.md rename to docs/architecture/TOPOLOGY.adoc index 1fb6c7ac..7035d77c 100644 --- a/docs/architecture/TOPOLOGY.md +++ b/docs/architecture/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== PanLL eNSAID — Project Topology -# PanLL eNSAID — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────────┐ │ HUMAN OPERATOR │ │ (Binary Star Co-orbit) │ @@ -98,11 +94,11 @@ │ - BoJ cartridges │ │ │ │ - BoJ-Server (:8080) │ │ - 11x IDApTIK cmds │ │ │ │ │ └───────────────────────┘ └───────────────────┘ └───────────────────────┘ -``` +.... -## Source File Inventory +=== Source File Inventory -``` +.... DIRECTORY FILES DESCRIPTION ───────────────────── ───── ───────────────────────────── src/model/ 192 Domain model types (1+ per panel + shared) @@ -120,11 +116,11 @@ panel-clades/clades/ 83 Clade definitions (a2ml) ───────────────────── ───── TOTAL SOURCE 510 412 ReScript + 98 Rust TOTAL TEST FILES 129 JS test suites (Deno.test) -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES CRG ────────────────────────────────── ────────────────── ─────────────────────────── ─── CORE PANELS (3) @@ -217,11 +213,11 @@ OVERALL PROGRESS ────────────────────────────────────────────────────────────────────────────────────── HONEST OVERALL █████████░ 95% Alpha complete, 2263 tests pass, 0 errors, 0 warnings ────────────────────────────────────────────────────────────────────────────────────── -``` +.... -## Cross-Panel Communication Map +=== Cross-Panel Communication Map -``` +.... Farm ──────> Reposystem (repo inventory -> compliance targets) | └────────> Hypatia (repo list -> scanning targets) @@ -271,11 +267,11 @@ A2ML/K9 ────> Clade Browser (Hunt permission -> clade isolation check) └────────> Feedback-O-Tron (test coverage policy -> quality reporting) Provisioner ──> ALL PANELS (isolation tier -> startup mode) -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... BUILD TOOLS ReScript compiler via npm (ADR accepted — npm kept for this only) Tailwind CSS via npm (same ADR) @@ -294,31 +290,41 @@ EXTERNAL SERVICES gitbot-fleet Axum API — bot orchestration Aerie V-lang API — network analysis Hypatia Elixir API — neurosymbolic CI/CD -``` - -## Honesty Notes - -- All 79 panels compile and render with 0 errors, 0 warnings -- TypeLL cross-panel intelligence is wired to all 48 implemented panels (100%) -- CRG grade D (Alpha) across every component — none have reached C (Beta, requires author dogfooding) -- 40 E2E panel lifecycle tests exist and pass (panel instantiation, TypeLL, routing) -- 28 game dev panels exist as clade definitions (a2ml) — ReScript implementation pending -- 3 new panels (K9 Manager, Contractile Manager, Wiring Inspector) added 2026-03-15 -- Source file count is 510 (.res + .rs); previous count of 361 predated game dev panels -- 2263 test assertions across 129 test files -- 39 Rust backend modules exist, but depth of implementation varies -- 6 .scm files migrated to .a2ml format on 2026-03-15 - -## Update Protocol +.... + +=== Honesty Notes + +* All 79 panels compile and render with 0 errors, 0 warnings +* TypeLL cross-panel intelligence is wired to all 48 implemented panels +(100%) +* CRG grade D (Alpha) across every component — none have reached C +(Beta, requires author dogfooding) +* 40 E2E panel lifecycle tests exist and pass (panel instantiation, +TypeLL, routing) +* 28 game dev panels exist as clade definitions (a2ml) — ReScript +implementation pending +* 3 new panels (K9 Manager, Contractile Manager, Wiring Inspector) added +2026-03-15 +* Source file count is 510 (.res + .rs); previous count of 361 predated +game dev panels +* 2263 test assertions across 129 test files +* 39 Rust backend modules exist, but depth of implementation varies +* 6 .scm files migrated to .a2ml format on 2026-03-15 + +=== Update Protocol This file is maintained by both humans and AI agents. When updating: -1. **After completing a component**: Change its bar, percentage, and CRG grade -2. **After adding a component**: Add a new row in the appropriate section -3. **After architectural changes**: Update the ASCII diagram -4. **After backend connection**: Move from Backend Connections 0% to actual % -5. **Date**: Update the `Last updated` comment at the top of this file - -Progress bars use: `█` (filled) and `░` (empty), 10 characters wide. -Percentages: 0%, 10%, 20%, ... 100% (in 10% increments). -CRG grades: X (untested), F (harmful), E (minimal), D (alpha), C (beta), B (RC), A (stable). +[arabic] +. *After completing a component*: Change its bar, percentage, and CRG +grade +. *After adding a component*: Add a new row in the appropriate section +. *After architectural changes*: Update the ASCII diagram +. *After backend connection*: Move from Backend Connections 0% to actual +% +. *Date*: Update the `+Last updated+` comment at the top of this file + +Progress bars use: `+█+` (filled) and `+░+` (empty), 10 characters wide. +Percentages: 0%, 10%, 20%, … 100% (in 10% increments). CRG grades: X +(untested), F (harmful), E (minimal), D (alpha), C (beta), B (RC), A +(stable). diff --git a/docs/archive/MIGRATION-TO-RESCRIPT-TEA.adoc b/docs/archive/MIGRATION-TO-RESCRIPT-TEA.adoc new file mode 100644 index 00000000..91c62f54 --- /dev/null +++ b/docs/archive/MIGRATION-TO-RESCRIPT-TEA.adoc @@ -0,0 +1,401 @@ +== Migration from Custom TEA to Official rescript-tea + +=== ⛔ SUPERSEDED — DO NOT FOLLOW + +*Decision (2026-03-08):* The custom TEA in `+src/tea/+` is PanLL’s +permanent architecture. This migration will not happen. See +`+docs/TEA_GUIDE.md+` §Permanence Decision for rationale. + +=== Overview (historical) + +This document tracked the migration from our custom TEA implementation +(`+src/tea/+`) to the official `+rescript-tea+` package (v0.16.0). + +=== Status: CANCELLED + +* [x] Install rescript-tea@0.16.0 +* [x] Update package.json +* [ ] Update imports to use Tea module from rescript-tea +* [ ] Migrate keyboard subscriptions +* [ ] Migrate Tauri command effects +* [ ] Test basic TEA cycle +* [ ] Remove custom src/tea/ directory (after migration complete) + +=== Module Mapping + +[width="100%",cols="34%,34%,17%,15%",options="header",] +|=== +|Custom Module |Official Module |Status |Notes +|`+src/tea/Tea.res+` |`+Tea+` (from rescript-tea) |🔄 Migrate |Main +entry point + +|`+src/tea/Tea_App.res+` |`+Tea.App+` or `+Tea_App+` |🔄 Migrate +|standardProgram available + +|`+src/tea/Tea_Cmd.res+` |`+Tea_Cmd+` |🔄 Migrate |Commands for side +effects + +|`+src/tea/Tea_Sub.res+` |`+Tea_Sub+` |🔄 Migrate |Subscriptions for +events + +|`+src/tea/Tea_Html.res+` |`+Tea_Html+` |🔄 Migrate |HTML DSL + +|`+src/tea/Tea_Vdom.res+` |`+Vdom+` |🔄 Migrate |Virtual DOM + +|`+src/tea/Tea_Render.res+` |(built-in) |🔄 Migrate |Handled by +rescript-tea +|=== + +=== Official rescript-tea Modules Available + +From `+node_modules/rescript-tea/src/+`: + +* ✅ `+tea_app.res+` - Application runtime +* ✅ `+tea_cmd.res+` - Commands +* ✅ `+tea_sub.res+` - Subscriptions +* ✅ `+tea_html.res+` - HTML DSL +* ✅ `+vdom.res+` - Virtual DOM +* ✅ `+tea_time.res+` - Time subscriptions +* ✅ `+tea_mouse.res+` - Mouse events +* ✅ `+tea_navigation.res+` - Routing/navigation *⭐* +* ✅ `+tea_http.res+` - HTTP requests +* ✅ `+tea_json.res+` - JSON encoding/decoding +* ✅ `+tea_task.res+` - Task abstraction +* ✅ `+tea_promise.res+` - Promise integration +* ✅ `+tea_animationframe.res+` - Animation frames +* ✅ `+tea_random.res+` - Random number generation +* ✅ `+tea_debug.res+` - Debugging utilities + +=== Key Differences + +==== 1. Import Syntax + +*Before (Custom)*: + +[source,rescript] +---- +open Tea.App +open Tea.Html +open Tea.Cmd +---- + +*After (Official)*: + +[source,rescript] +---- +open Tea_App +open Tea_Html +// Cmd is accessed via Tea_Cmd module +---- + +==== 2. Commands + +*Official rescript-tea* provides `+Tea_Cmd+` with: - `+Tea_Cmd.none+` - +No command - `+Tea_Cmd.batch(list)+` - Multiple commands - +`+Tea_Cmd.call(callback)+` - Custom command + +==== 3. Subscriptions + +*Official rescript-tea* provides `+Tea_Sub+` with: - `+Tea_Sub.none+` - +No subscription - `+Tea_Sub.batch(list)+` - Multiple subscriptions + +*Available subscriptions:* - `+Tea_Time.every(interval, msg)+` - Timer - +`+Tea_Mouse.clicks(msg)+` - Mouse clicks - `+Tea_Mouse.moves(msg)+` - +Mouse moves - `+Tea_Animationframe.onAnimationFrame(msg)+` - Animation +frames - `+Tea_Navigation.onChange(url => msg)+` - URL changes + +==== 4. Keyboard Events + +*rescript-tea doesn’t have built-in keyboard subscriptions!* + +We need to create custom subscriptions for keyboard events: + +[source,rescript] +---- +// src/subscriptions/Keyboard.res +module Keyboard = { + type keyEvent = { + key: string, + ctrlKey: bool, + shiftKey: bool, + altKey: bool, + } + + @val external addEventListener: (string, Js.t<'a> => unit) => unit = "window.addEventListener" + @val external removeEventListener: (string, Js.t<'a> => unit) => unit = "window.removeEventListener" + + let onKeyDown = (tagger: keyEvent => 'msg): Tea_Sub.t<'msg> => { + Tea_Sub.registration( + "keyboard-keydown", + enabler => { + let handler = evt => { + let key = evt["key"] + let ctrlKey = evt["ctrlKey"] + let shiftKey = evt["shiftKey"] + let altKey = evt["altKey"] + enabler(tagger({key, ctrlKey, shiftKey, altKey})) + } + addEventListener("keydown", handler) + () => removeEventListener("keydown", handler) + } + ) + } +} +---- + +==== 5. Tauri Commands + +We need custom commands for Tauri: + +[source,rescript] +---- +// src/commands/TauriCmd.res +module TauriCmd = { + @module("@tauri-apps/api/core") external invoke: (string, 'a) => promise<'b> = "invoke" + + let validateInference = (token: string, constraints: array, tagger: result => 'msg): Tea_Cmd.t<'msg> => { + Tea_Cmd.call(callbacks => { + invoke("validate_inference", {"token": token, "constraints": constraints}) + ->Promise.then(result => { + callbacks.enqueue(tagger(Ok(result))) + Promise.resolve() + }) + ->Promise.catch(err => { + callbacks.enqueue(tagger(Error("Validation failed"))) + Promise.resolve() + }) + ->ignore + }) + } + + let getVexationIndex = (tagger: float => 'msg): Tea_Cmd.t<'msg> => { + Tea_Cmd.call(callbacks => { + invoke("get_vexation_index", ()) + ->Promise.then(result => { + callbacks.enqueue(tagger(result)) + Promise.resolve() + }) + ->ignore + }) + } +} +---- + +==== 6. Navigation/Routing + +For a Tauri desktop app, we might not need traditional URL-based +routing. Instead: + +*Option A: View-based routing* (simpler, recommended for PanLL) + +[source,rescript] +---- +type route = + | ThreePaneView + | SettingsView + | FeedbackView + +type model = { + currentRoute: route, + // ... other fields +} +---- + +*Option B: Use Tea_Navigation* (if you want URL-like routes) + +[source,rescript] +---- +// Use Tea_Navigation for hash-based routing +let subscriptions = (model: model): Tea_Sub.t => { + Tea_Navigation.onChange(url => UrlChanged(url)) +} +---- + +=== Migration Steps + +==== Step 1: Update App.res + +*Before*: + +[source,rescript] +---- +open Tea.App + +let main = standardProgram({ + init: () => (Model.init(), Tea.Cmd.none), + update: Update.update, + view: View.view, + subscriptions: _ => Tea.Sub.none, +}) +---- + +*After*: + +[source,rescript] +---- +// Use official rescript-tea +let main = Tea_App.standardProgram( + ~init=() => (Model.init(), Tea_Cmd.none), + ~update=Update.update, + ~view=View.view, + ~subscriptions=Subscriptions.subscriptions, + () +) +---- + +==== Step 2: Create Subscriptions.res + +[source,rescript] +---- +// src/Subscriptions.res +open Model +open Msg + +let subscriptions = (model: model): Tea_Sub.t => { + Tea_Sub.batch(list{ + // Keyboard shortcuts + Keyboard.onKeyDown(evt => { + if evt.ctrlKey && evt.shiftKey { + switch evt.key { + | "L" => View(TogglePaneL) + | "N" => View(TogglePaneN) + | "B" => View(TogglePaneW) + | _ => NoOp + } + } else { + NoOp + } + }), + + // Update vexation index every second + Tea_Time.every(1000.0, _ => Vexometer(UpdateVexationIndex(0.0))), + + // Animation frame for smooth UI + Tea_Animationframe.onAnimationFrame(_ => NoOp), + }) +} +---- + +==== Step 3: Update Update.res to use Commands + +[source,rescript] +---- +let update = (model: model, msg: msg): (model, Tea_Cmd.t) => { + switch msg { + | AntiCrash(ValidateToken(token)) => { + let newModel = model + let cmd = TauriCmd.validateInference( + token.content, + model.paneL.constraints->Array.map(c => c.expression), + result => { + switch result { + | Ok(valid) => AntiCrash(ValidationPassed(token)) + | Error(reason) => AntiCrash(ValidationFailed(token, reason)) + } + } + ) + (newModel, cmd) + } + + | Vexometer(UpdateVexationIndex(_)) => { + let cmd = TauriCmd.getVexationIndex(index => + Vexometer(UpdateVexationIndex(index)) + ) + (model, cmd) + } + + | _ => { + // ... other message handlers + (model, Tea_Cmd.none) + } + } +} +---- + +==== Step 4: Update View imports + +[source,rescript] +---- +// src/View.res +open Tea_Html // Changed from Tea.Html +open Model +open Msg + +let view = (model: model): Vdom.t => { + // ... view code +} +---- + +==== Step 5: Test the migration + +[source,bash] +---- +# Clean build +npm run res:clean + +# Build +npm run res:build + +# Run Tauri dev +deno task dev +---- + +==== Step 6: Remove custom TEA (after successful migration) + +[source,bash] +---- +# Once everything works with official rescript-tea: +rm -rf src/tea/ +git add -A +git commit -m "refactor: migrate from custom TEA to rescript-tea@0.16.0" +---- + +=== Testing Checklist + +* [ ] App loads without errors +* [ ] Three panes render correctly +* [ ] Keyboard shortcuts work (Ctrl+Shift+L/N/B) +* [ ] Vexation index updates +* [ ] Tauri commands can be invoked +* [ ] State updates correctly +* [ ] No console errors + +=== Benefits of Official rescript-tea + +[arabic] +. *Battle-tested*: Used in production by Darklang and others +. *More features*: Navigation, HTTP, Time, Mouse, AnimationFrame +. *Community support*: Issues, PRs, updates +. *Less maintenance*: We don’t have to maintain TEA runtime +. *Better performance*: Optimized virtual DOM +. *Documentation*: Follows Elm’s well-documented architecture + +=== Rollback Plan + +If migration fails, we can rollback by: + +[source,bash] +---- +git revert +npm install # Restore dependencies +npm run res:build +---- + +The custom TEA implementation remains in `+src/tea/+` until migration is +confirmed successful. + +=== Next Steps After Migration + +[arabic] +. ✅ Basic TEA cycle working +. ✅ Keyboard shortcuts functional +. ✅ Tauri integration working +. Add HTTP requests for future features +. Add proper error handling +. Add debugging with Tea_Debug +. Consider adding Tea_Navigation for view routing + +''''' + +*Migration Started*: 2026-02-04 *Target Completion*: 2026-02-11 (1 week) +*Assigned*: Claude + User diff --git a/docs/archive/MIGRATION-TO-RESCRIPT-TEA.md b/docs/archive/MIGRATION-TO-RESCRIPT-TEA.md deleted file mode 100644 index 323178c7..00000000 --- a/docs/archive/MIGRATION-TO-RESCRIPT-TEA.md +++ /dev/null @@ -1,367 +0,0 @@ -# Migration from Custom TEA to Official rescript-tea - -## ⛔ SUPERSEDED — DO NOT FOLLOW - -**Decision (2026-03-08):** The custom TEA in `src/tea/` is PanLL's permanent -architecture. This migration will not happen. See `docs/TEA_GUIDE.md` §Permanence -Decision for rationale. - -## Overview (historical) - -This document tracked the migration from our custom TEA implementation (`src/tea/`) to the official `rescript-tea` package (v0.16.0). - -## Status: CANCELLED - -- [x] Install rescript-tea@0.16.0 -- [x] Update package.json -- [ ] Update imports to use Tea module from rescript-tea -- [ ] Migrate keyboard subscriptions -- [ ] Migrate Tauri command effects -- [ ] Test basic TEA cycle -- [ ] Remove custom src/tea/ directory (after migration complete) - -## Module Mapping - -| Custom Module | Official Module | Status | Notes | -|---------------|----------------|--------|-------| -| `src/tea/Tea.res` | `Tea` (from rescript-tea) | 🔄 Migrate | Main entry point | -| `src/tea/Tea_App.res` | `Tea.App` or `Tea_App` | 🔄 Migrate | standardProgram available | -| `src/tea/Tea_Cmd.res` | `Tea_Cmd` | 🔄 Migrate | Commands for side effects | -| `src/tea/Tea_Sub.res` | `Tea_Sub` | 🔄 Migrate | Subscriptions for events | -| `src/tea/Tea_Html.res` | `Tea_Html` | 🔄 Migrate | HTML DSL | -| `src/tea/Tea_Vdom.res` | `Vdom` | 🔄 Migrate | Virtual DOM | -| `src/tea/Tea_Render.res` | (built-in) | 🔄 Migrate | Handled by rescript-tea | - -## Official rescript-tea Modules Available - -From `node_modules/rescript-tea/src/`: - -- ✅ `tea_app.res` - Application runtime -- ✅ `tea_cmd.res` - Commands -- ✅ `tea_sub.res` - Subscriptions -- ✅ `tea_html.res` - HTML DSL -- ✅ `vdom.res` - Virtual DOM -- ✅ `tea_time.res` - Time subscriptions -- ✅ `tea_mouse.res` - Mouse events -- ✅ `tea_navigation.res` - Routing/navigation **⭐** -- ✅ `tea_http.res` - HTTP requests -- ✅ `tea_json.res` - JSON encoding/decoding -- ✅ `tea_task.res` - Task abstraction -- ✅ `tea_promise.res` - Promise integration -- ✅ `tea_animationframe.res` - Animation frames -- ✅ `tea_random.res` - Random number generation -- ✅ `tea_debug.res` - Debugging utilities - -## Key Differences - -### 1. Import Syntax - -**Before (Custom)**: -```rescript -open Tea.App -open Tea.Html -open Tea.Cmd -``` - -**After (Official)**: -```rescript -open Tea_App -open Tea_Html -// Cmd is accessed via Tea_Cmd module -``` - -### 2. Commands - -**Official rescript-tea** provides `Tea_Cmd` with: -- `Tea_Cmd.none` - No command -- `Tea_Cmd.batch(list)` - Multiple commands -- `Tea_Cmd.call(callback)` - Custom command - -### 3. Subscriptions - -**Official rescript-tea** provides `Tea_Sub` with: -- `Tea_Sub.none` - No subscription -- `Tea_Sub.batch(list)` - Multiple subscriptions - -**Available subscriptions:** -- `Tea_Time.every(interval, msg)` - Timer -- `Tea_Mouse.clicks(msg)` - Mouse clicks -- `Tea_Mouse.moves(msg)` - Mouse moves -- `Tea_Animationframe.onAnimationFrame(msg)` - Animation frames -- `Tea_Navigation.onChange(url => msg)` - URL changes - -### 4. Keyboard Events - -**rescript-tea doesn't have built-in keyboard subscriptions!** - -We need to create custom subscriptions for keyboard events: - -```rescript -// src/subscriptions/Keyboard.res -module Keyboard = { - type keyEvent = { - key: string, - ctrlKey: bool, - shiftKey: bool, - altKey: bool, - } - - @val external addEventListener: (string, Js.t<'a> => unit) => unit = "window.addEventListener" - @val external removeEventListener: (string, Js.t<'a> => unit) => unit = "window.removeEventListener" - - let onKeyDown = (tagger: keyEvent => 'msg): Tea_Sub.t<'msg> => { - Tea_Sub.registration( - "keyboard-keydown", - enabler => { - let handler = evt => { - let key = evt["key"] - let ctrlKey = evt["ctrlKey"] - let shiftKey = evt["shiftKey"] - let altKey = evt["altKey"] - enabler(tagger({key, ctrlKey, shiftKey, altKey})) - } - addEventListener("keydown", handler) - () => removeEventListener("keydown", handler) - } - ) - } -} -``` - -### 5. Tauri Commands - -We need custom commands for Tauri: - -```rescript -// src/commands/TauriCmd.res -module TauriCmd = { - @module("@tauri-apps/api/core") external invoke: (string, 'a) => promise<'b> = "invoke" - - let validateInference = (token: string, constraints: array, tagger: result => 'msg): Tea_Cmd.t<'msg> => { - Tea_Cmd.call(callbacks => { - invoke("validate_inference", {"token": token, "constraints": constraints}) - ->Promise.then(result => { - callbacks.enqueue(tagger(Ok(result))) - Promise.resolve() - }) - ->Promise.catch(err => { - callbacks.enqueue(tagger(Error("Validation failed"))) - Promise.resolve() - }) - ->ignore - }) - } - - let getVexationIndex = (tagger: float => 'msg): Tea_Cmd.t<'msg> => { - Tea_Cmd.call(callbacks => { - invoke("get_vexation_index", ()) - ->Promise.then(result => { - callbacks.enqueue(tagger(result)) - Promise.resolve() - }) - ->ignore - }) - } -} -``` - -### 6. Navigation/Routing - -For a Tauri desktop app, we might not need traditional URL-based routing. Instead: - -**Option A: View-based routing** (simpler, recommended for PanLL) -```rescript -type route = - | ThreePaneView - | SettingsView - | FeedbackView - -type model = { - currentRoute: route, - // ... other fields -} -``` - -**Option B: Use Tea_Navigation** (if you want URL-like routes) -```rescript -// Use Tea_Navigation for hash-based routing -let subscriptions = (model: model): Tea_Sub.t => { - Tea_Navigation.onChange(url => UrlChanged(url)) -} -``` - -## Migration Steps - -### Step 1: Update App.res - -**Before**: -```rescript -open Tea.App - -let main = standardProgram({ - init: () => (Model.init(), Tea.Cmd.none), - update: Update.update, - view: View.view, - subscriptions: _ => Tea.Sub.none, -}) -``` - -**After**: -```rescript -// Use official rescript-tea -let main = Tea_App.standardProgram( - ~init=() => (Model.init(), Tea_Cmd.none), - ~update=Update.update, - ~view=View.view, - ~subscriptions=Subscriptions.subscriptions, - () -) -``` - -### Step 2: Create Subscriptions.res - -```rescript -// src/Subscriptions.res -open Model -open Msg - -let subscriptions = (model: model): Tea_Sub.t => { - Tea_Sub.batch(list{ - // Keyboard shortcuts - Keyboard.onKeyDown(evt => { - if evt.ctrlKey && evt.shiftKey { - switch evt.key { - | "L" => View(TogglePaneL) - | "N" => View(TogglePaneN) - | "B" => View(TogglePaneW) - | _ => NoOp - } - } else { - NoOp - } - }), - - // Update vexation index every second - Tea_Time.every(1000.0, _ => Vexometer(UpdateVexationIndex(0.0))), - - // Animation frame for smooth UI - Tea_Animationframe.onAnimationFrame(_ => NoOp), - }) -} -``` - -### Step 3: Update Update.res to use Commands - -```rescript -let update = (model: model, msg: msg): (model, Tea_Cmd.t) => { - switch msg { - | AntiCrash(ValidateToken(token)) => { - let newModel = model - let cmd = TauriCmd.validateInference( - token.content, - model.paneL.constraints->Array.map(c => c.expression), - result => { - switch result { - | Ok(valid) => AntiCrash(ValidationPassed(token)) - | Error(reason) => AntiCrash(ValidationFailed(token, reason)) - } - } - ) - (newModel, cmd) - } - - | Vexometer(UpdateVexationIndex(_)) => { - let cmd = TauriCmd.getVexationIndex(index => - Vexometer(UpdateVexationIndex(index)) - ) - (model, cmd) - } - - | _ => { - // ... other message handlers - (model, Tea_Cmd.none) - } - } -} -``` - -### Step 4: Update View imports - -```rescript -// src/View.res -open Tea_Html // Changed from Tea.Html -open Model -open Msg - -let view = (model: model): Vdom.t => { - // ... view code -} -``` - -### Step 5: Test the migration - -```bash -# Clean build -npm run res:clean - -# Build -npm run res:build - -# Run Tauri dev -deno task dev -``` - -### Step 6: Remove custom TEA (after successful migration) - -```bash -# Once everything works with official rescript-tea: -rm -rf src/tea/ -git add -A -git commit -m "refactor: migrate from custom TEA to rescript-tea@0.16.0" -``` - -## Testing Checklist - -- [ ] App loads without errors -- [ ] Three panes render correctly -- [ ] Keyboard shortcuts work (Ctrl+Shift+L/N/B) -- [ ] Vexation index updates -- [ ] Tauri commands can be invoked -- [ ] State updates correctly -- [ ] No console errors - -## Benefits of Official rescript-tea - -1. **Battle-tested**: Used in production by Darklang and others -2. **More features**: Navigation, HTTP, Time, Mouse, AnimationFrame -3. **Community support**: Issues, PRs, updates -4. **Less maintenance**: We don't have to maintain TEA runtime -5. **Better performance**: Optimized virtual DOM -6. **Documentation**: Follows Elm's well-documented architecture - -## Rollback Plan - -If migration fails, we can rollback by: -```bash -git revert -npm install # Restore dependencies -npm run res:build -``` - -The custom TEA implementation remains in `src/tea/` until migration is confirmed successful. - -## Next Steps After Migration - -1. ✅ Basic TEA cycle working -2. ✅ Keyboard shortcuts functional -3. ✅ Tauri integration working -4. Add HTTP requests for future features -5. Add proper error handling -6. Add debugging with Tea_Debug -7. Consider adding Tea_Navigation for view routing - ---- - -**Migration Started**: 2026-02-04 -**Target Completion**: 2026-02-11 (1 week) -**Assigned**: Claude + User diff --git a/docs/archive/NPM-TO-DENO-MIGRATION.adoc b/docs/archive/NPM-TO-DENO-MIGRATION.adoc new file mode 100644 index 00000000..6a3f28f3 --- /dev/null +++ b/docs/archive/NPM-TO-DENO-MIGRATION.adoc @@ -0,0 +1,490 @@ +== npm → Deno Migration Plan for PanLL + +____ +*STATUS: CLOSED (2026-05-30).* Closed by panll#65 — `+package.json+` and +`+package-lock.json+` deleted; ReScript + Tailwind now run through +`+npm:+` specifiers in `+deno.json+`. See the `+deno.json+` task table +and `+.github/workflows/build-validation.yml+` for the shipped state. +The text below is preserved as the original planning document for +historical context; details may not reflect what actually shipped. +____ + +*Status:* Planning phase (superseded) *Priority:* Medium (blocks full +hyperpolymath policy compliance) *Timeline:* 1-2 weeks implementation +*Blocker:* ReScript compiler requires Node.js/npm (no Deno support yet) + +''''' + +=== Executive Summary + +PanLL currently uses a *hybrid npm + Deno build system* which violates +hyperpolymath policy (Deno-only runtime). This document outlines a +migration strategy to *minimize npm usage to ReScript compilation only*, +with a path to *full elimination when ReScript adds Deno support*. + +==== Current State (npm + Deno Hybrid) + +.... +npm: ReScript compilation, Tailwind, Tauri CLI, testing (Vitest) +Deno: Tailwind orchestration, Tauri dev runner +.... + +==== Target State (Deno Primary, npm Minimal) + +.... +npm: ReScript compilation ONLY +Deno: Tailwind, Tauri orchestration, testing, all other tasks +.... + +==== Future State (Deno Only) + +.... +npm: (eliminated) +Deno: Everything (when ReScript supports Deno) +.... + +''''' + +=== Current Dependencies Analysis + +==== package.json Dependencies + +[width="100%",cols="18%,15%,15%,31%,21%",options="header",] +|=== +|Package |Version |Purpose |Deno Alternative |Eliminate? +|`+rescript+` |11.1.4 |ReScript compiler |❌ None (blocker) |⏳ When +ReScript supports Deno + +|`+@rescript/core+` |1.6.1 |ReScript stdlib |❌ None (blocker) |⏳ When +ReScript supports Deno + +|`+rescript-webapi+` |0.10.0 |Browser API bindings |❌ None (blocker) +|⏳ When ReScript supports Deno + +|`+@tauri-apps/cli+` |2.0.0 |Tauri CLI |✅ `+cargo install tauri-cli+` +|✅ Yes + +|`+tailwindcss+` |4.1.18 |CSS framework |✅ `+deno run npm:tailwindcss+` +|✅ Yes + +|`+vitest+` |4.0.18 |Testing framework |✅ `+Deno.test+` |✅ Yes + +|`+@vitest/ui+` |4.0.18 |Test UI |✅ Not needed (Deno test reporter) |✅ +Yes + +|`+@vitest/coverage-v8+` |4.0.18 |Coverage |✅ `+deno coverage+` |✅ Yes + +|`+happy-dom+` |20.5.0 |DOM simulation |✅ Deno native DOM APIs |✅ Yes +|=== + +==== Key Findings + +[arabic] +. *ReScript ecosystem* (rescript, @rescript/core, rescript-webapi) has +*no Deno support* → blocker for full elimination +. *Tauri CLI* can be installed via Cargo instead of npm +. *Tailwind CSS* can run directly via Deno +(`+deno run npm:tailwindcss+`) +. *Vitest* can be replaced with Deno’s native test runner +. *happy-dom* unnecessary (Deno has native DOM simulation) + +''''' + +=== Migration Strategy: Three Phases + +==== Phase 1: Eliminate Tauri CLI from npm ✅ (Ready Now) + +*Goal:* Install Tauri CLI via Cargo instead of npm + +*Steps:* 1. Install Tauri CLI globally: `+cargo install tauri-cli+` 2. +Update deno.json tasks to use `+tauri+` (from PATH) instead of +`+npx @tauri-apps/cli+` 3. Remove `+@tauri-apps/cli+` from package.json +devDependencies 4. Test: `+deno task dev+` should work with global +`+tauri+` command + +*Impact:* Removes 1 npm dependency + +''''' + +==== Phase 2: Replace Vitest with Deno.test ✅ (Ready Now) + +*Goal:* Migrate tests from Vitest to Deno’s native test runner + +===== Current Test Setup (Vitest) + +[source,javascript] +---- +// tests/Tea_App.test.js +import { describe, test, expect } from 'vitest'; +import { TeaApp } from '../lib/es6/src/tea/Tea_App.res.js'; + +describe('Tea_App', () => { + test('should initialize app', () => { + // Test logic + }); +}); +---- + +===== Target Test Setup (Deno.test) + +[source,javascript] +---- +// tests/tea_app_test.ts +import { assertEquals, assertExists } from "jsr:@std/assert"; +import { TeaApp } from "../lib/es6/src/tea/Tea_App.res.js"; + +Deno.test("Tea_App - should initialize app", () => { + // Test logic using assertEquals/assertExists +}); + +Deno.test("Tea_App - should handle commands", () => { + // Test logic +}); +---- + +===== Migration Steps + +[arabic] +. *Convert test files:* +* Rename `+tests/*.test.js+` → `+tests/*_test.ts+` +* Replace Vitest imports with `+jsr:@std/assert+` +* Replace `+describe()+` + `+test()+` with flat `+Deno.test()+` +* Replace `+expect().toBe()+` with `+assertEquals()+` +. *Update deno.json:* ++ +[source,json] +---- +{ + "tasks": { + "test": "deno test --allow-read --allow-env tests/", + "test:watch": "deno test --watch --allow-read --allow-env tests/", + "test:coverage": "deno test --coverage=coverage/ tests/ && deno coverage coverage/" + } +} +---- +. *Remove Vitest from package.json:* +* Remove `+vitest+`, `+@vitest/ui+`, `+@vitest/coverage-v8+`, +`+happy-dom+` +. *Update npm scripts in package.json:* +* Remove `+"test": "vitest run"+` +* Remove `+"test:watch": "vitest"+` +* Remove `+"test:ui": "vitest --ui"+` +* Remove `+"test:coverage": "vitest run --coverage"+` +. *Update CI/CD workflows* (`+.github/workflows/*.yml+`): +* Replace `+npm run test+` with `+deno task test+` +. *Update PLAYBOOK.scm:* +* Document new Deno test commands +* Update testing procedures + +*Impact:* Removes 4 npm dependencies (vitest, @vitest/ui, +@vitest/coverage-v8, happy-dom) + +''''' + +==== Phase 3: Minimize npm to ReScript Only ✅ (Ready Now) + +*Goal:* Keep npm ONLY for ReScript compilation + +===== Final package.json (Minimal) + +[source,json] +---- +{ + "name": "panll", + "version": "0.1.0", + "type": "module", + "scripts": { + "res:build": "rescript build", + "res:watch": "rescript build -w", + "res:clean": "rescript clean" + }, + "devDependencies": { + "rescript": "^11.1.4", + "@rescript/core": "^1.6.1" + }, + "dependencies": { + "rescript-webapi": "^0.10.0" + } +} +---- + +===== Final deno.json (Primary) + +[source,json] +---- +{ + "name": "@hyperpolymath/panll", + "version": "0.1.0", + "permissions": { + "read": true, + "write": ["./public", "./coverage"], + "run": true, + "env": true + }, + "tasks": { + "dev": "deno task css:watch & tauri dev", + "build": "deno task css:build && tauri build", + "css:build": "deno run -A npm:tailwindcss@4.1.18 -i ./src/styles/input.css -o ./public/styles.css --minify", + "css:watch": "deno run -A npm:tailwindcss@4.1.18 -i ./src/styles/input.css -o ./public/styles.css --watch", + "test": "deno test --allow-read --allow-env tests/", + "test:watch": "deno test --watch --allow-read --allow-env tests/", + "test:coverage": "deno test --coverage=coverage/ tests/ && deno coverage coverage/", + "lint": "deno lint src/ tests/", + "fmt": "deno fmt src/ tests/" + }, + "imports": { + "@std/": "jsr:@std/", + "@std/assert": "jsr:@std/assert@^1.0.0" + }, + "compilerOptions": { + "strict": true, + "noImplicitAny": true + } +} +---- + +*Impact:* npm usage reduced to 3 packages (ReScript only), all other +tasks via Deno + +''''' + +=== Implementation Plan + +==== Step 1: Backup Current Setup ✅ + +[source,bash] +---- +git checkout -b feature/npm-to-deno-migration +git add -A +git commit -m "chore: checkpoint before npm→Deno migration" +---- + +==== Step 2: Phase 1 - Eliminate Tauri CLI npm ✅ + +[source,bash] +---- +# Install Tauri CLI via Cargo +cargo install tauri-cli + +# Verify installation +tauri --version # Should show "tauri-cli 2.x.x" + +# Update deno.json (already uses `tauri` command, no changes needed) + +# Remove from package.json +npm uninstall @tauri-apps/cli + +# Test +deno task dev # Should work with global tauri +---- + +==== Step 3: Phase 2 - Migrate Tests to Deno ✅ + +[source,bash] +---- +# Convert test files (manual or script-assisted) +# Example: tests/Tea_App.test.js → tests/tea_app_test.ts + +# Update imports and assertions +# Vitest → @std/assert + +# Remove Vitest from package.json +npm uninstall vitest @vitest/ui @vitest/coverage-v8 happy-dom + +# Update deno.json with test tasks (see Phase 2 above) + +# Run tests +deno task test # Should pass (33 tests) + +# Generate coverage +deno task test:coverage +---- + +==== Step 4: Phase 3 - Finalize Migration ✅ + +[source,bash] +---- +# Verify package.json contains only ReScript deps + +# Update README.adoc with new commands: +# - npm run res:build (ReScript compilation) +# - deno task dev (Tauri + Tailwind) +# - deno task test (Deno tests) + +# Update PLAYBOOK.scm with new procedures + +# Commit +git add -A +git commit -m "feat: migrate to Deno-primary build system (npm for ReScript only)" +---- + +==== Step 5: Update Documentation ✅ + +Files to update: - [x] `+README.adoc+` - Build commands, prerequisites - +[x] `+PLAYBOOK.scm+` - Operational procedures, common commands - [x] +`+STATE.scm+` - Mark migration completed in work-completed - [x] +`+.github/workflows/*.yml+` - CI/CD commands (if any) + +==== Step 6: Test Thoroughly ✅ + +[source,bash] +---- +# Clean slate +npm run res:clean +rm -rf node_modules coverage/ +npm install + +# Full build cycle +npm run res:build +deno task css:build +deno task dev # Verify app launches + +# Test suite +deno task test # Verify all tests pass +deno task test:coverage # Verify coverage meets target (87-91%) + +# Manual testing +# - Three panes render correctly +# - Keyboard shortcuts work (Ctrl+Shift+L/N/W) +# - No console errors +---- + +''''' + +=== Testing Strategy + +==== Regression Testing + +* [x] All 33 tests converted and passing +* [x] Coverage maintained at 87-91%+ +* [x] App launches without errors +* [x] Three panes render correctly +* [x] Keyboard shortcuts functional +* [x] Tauri commands work (validate_inference, get_vexation_index) + +==== Performance Testing + +* Compare build times: `+npm+` vs `+deno task+` +* Verify hot reload still works with Deno tasks +* Measure test execution time: Vitest vs Deno.test + +''''' + +=== Rollback Plan + +If migration fails: + +[source,bash] +---- +# Revert to checkpoint +git reset --hard HEAD~1 + +# Reinstall npm dependencies +npm install + +# Verify old system works +npm run test +deno task dev +---- + +Keep migration branch for future attempts. + +''''' + +=== Future: Full npm Elimination + +==== Blocker: ReScript Deno Support + +*Current:* ReScript compiler built on Node.js, no Deno support +*Tracking:* https://github.com/rescript-lang/rescript-compiler/issues/ + +*When ReScript supports Deno:* + +[arabic] +. Remove `+package.json+` entirely +. Move ReScript compilation to `+deno.json+`: ++ +[source,json] +---- +{ + "tasks": { + "res:build": "deno run -A jsr:@rescript/compiler build", + "res:watch": "deno run -A jsr:@rescript/compiler build -w" + } +} +---- +. Update `+rescript.json+` to use Deno paths +. Remove `+node_modules/+` from `+.gitignore+` +. Document in PLAYBOOK.scm + +*Alternative:* If ReScript never supports Deno, consider: - Migrating to +Gleam (compiles to JS, Deno-compatible) - Migrating to PureScript +(Deno-compatible) - Staying with minimal npm (acceptable compromise) + +''''' + +=== Benefits of Migration + +==== Policy Compliance ✅ + +* Follows hyperpolymath Deno-first policy +* Reduces npm surface area from 9 deps → 3 deps +* Clear separation: npm = ReScript only, Deno = everything else + +==== Developer Experience 📈 + +* Fewer package managers (Deno primary, npm minimal) +* Faster installs (Deno caches jsr/npm imports) +* Native test runner (no Vitest config) +* Better error messages (Deno’s stack traces) + +==== Performance 🚀 + +* Deno.test faster than Vitest (no transpilation) +* Tailwind via Deno faster (no npm overhead) +* Smaller node_modules (only ReScript deps) + +==== Security 🔒 + +* Deno explicit permissions (–allow-read, –allow-run) +* Fewer npm dependencies = smaller attack surface +* cargo-installed Tauri CLI (no npm supply chain risk) + +''''' + +=== Open Questions + +[arabic] +. *Coverage reporting:* Deno coverage format compatible with CI/CD? +. *Test UI:* Vitest UI useful - Deno equivalent? +. *ReScript timeline:* When (if ever) will ReScript support Deno? +. *Breaking changes:* Does migration break any workflows? + +''''' + +=== Success Criteria + +* [x] `+package.json+` contains ≤3 dependencies (ReScript ecosystem +only) +* [x] All build tasks run via `+deno task+` (except ReScript +compilation) +* [x] All tests pass with `+deno test+` +* [x] Coverage ≥87% maintained +* [x] App launches and functions correctly +* [x] Documentation updated (README, PLAYBOOK) +* [x] Migration completed within 1-2 weeks + +''''' + +*Status:* Ready for implementation *Assignee:* TBD *Estimated Effort:* +3-5 days (Phase 1-3) *Risk Level:* Low (incremental migration, rollback +available) + +''''' + +=== Related Documents + +* `+MIGRATION-TO-RESCRIPT-TEA.md+` - TEA library migration +* `+PLAYBOOK.scm+` - Operational procedures +* `+STATE.scm+` - Project state and blockers +* `+~/.claude/CLAUDE.md+` - Hyperpolymath language policy diff --git a/docs/archive/NPM-TO-DENO-MIGRATION.md b/docs/archive/NPM-TO-DENO-MIGRATION.md deleted file mode 100644 index c17db873..00000000 --- a/docs/archive/NPM-TO-DENO-MIGRATION.md +++ /dev/null @@ -1,453 +0,0 @@ -# npm → Deno Migration Plan for PanLL - -> **STATUS: CLOSED (2026-05-30).** Closed by panll#65 — `package.json` and -> `package-lock.json` deleted; ReScript + Tailwind now run through `npm:` -> specifiers in `deno.json`. See the `deno.json` task table and -> `.github/workflows/build-validation.yml` for the shipped state. The text -> below is preserved as the original planning document for historical context; -> details may not reflect what actually shipped. - -**Status:** Planning phase (superseded) -**Priority:** Medium (blocks full hyperpolymath policy compliance) -**Timeline:** 1-2 weeks implementation -**Blocker:** ReScript compiler requires Node.js/npm (no Deno support yet) - ---- - -## Executive Summary - -PanLL currently uses a **hybrid npm + Deno build system** which violates hyperpolymath policy (Deno-only runtime). This document outlines a migration strategy to **minimize npm usage to ReScript compilation only**, with a path to **full elimination when ReScript adds Deno support**. - -### Current State (npm + Deno Hybrid) - -``` -npm: ReScript compilation, Tailwind, Tauri CLI, testing (Vitest) -Deno: Tailwind orchestration, Tauri dev runner -``` - -### Target State (Deno Primary, npm Minimal) - -``` -npm: ReScript compilation ONLY -Deno: Tailwind, Tauri orchestration, testing, all other tasks -``` - -### Future State (Deno Only) - -``` -npm: (eliminated) -Deno: Everything (when ReScript supports Deno) -``` - ---- - -## Current Dependencies Analysis - -### package.json Dependencies - -| Package | Version | Purpose | Deno Alternative | Eliminate? | -|---------|---------|---------|------------------|------------| -| `rescript` | 11.1.4 | ReScript compiler | ❌ None (blocker) | ⏳ When ReScript supports Deno | -| `@rescript/core` | 1.6.1 | ReScript stdlib | ❌ None (blocker) | ⏳ When ReScript supports Deno | -| `rescript-webapi` | 0.10.0 | Browser API bindings | ❌ None (blocker) | ⏳ When ReScript supports Deno | -| `@tauri-apps/cli` | 2.0.0 | Tauri CLI | ✅ `cargo install tauri-cli` | ✅ Yes | -| `tailwindcss` | 4.1.18 | CSS framework | ✅ `deno run npm:tailwindcss` | ✅ Yes | -| `vitest` | 4.0.18 | Testing framework | ✅ `Deno.test` | ✅ Yes | -| `@vitest/ui` | 4.0.18 | Test UI | ✅ Not needed (Deno test reporter) | ✅ Yes | -| `@vitest/coverage-v8` | 4.0.18 | Coverage | ✅ `deno coverage` | ✅ Yes | -| `happy-dom` | 20.5.0 | DOM simulation | ✅ Deno native DOM APIs | ✅ Yes | - -### Key Findings - -1. **ReScript ecosystem** (rescript, @rescript/core, rescript-webapi) has **no Deno support** → blocker for full elimination -2. **Tauri CLI** can be installed via Cargo instead of npm -3. **Tailwind CSS** can run directly via Deno (`deno run npm:tailwindcss`) -4. **Vitest** can be replaced with Deno's native test runner -5. **happy-dom** unnecessary (Deno has native DOM simulation) - ---- - -## Migration Strategy: Three Phases - -### Phase 1: Eliminate Tauri CLI from npm ✅ (Ready Now) - -**Goal:** Install Tauri CLI via Cargo instead of npm - -**Steps:** -1. Install Tauri CLI globally: `cargo install tauri-cli` -2. Update deno.json tasks to use `tauri` (from PATH) instead of `npx @tauri-apps/cli` -3. Remove `@tauri-apps/cli` from package.json devDependencies -4. Test: `deno task dev` should work with global `tauri` command - -**Impact:** Removes 1 npm dependency - ---- - -### Phase 2: Replace Vitest with Deno.test ✅ (Ready Now) - -**Goal:** Migrate tests from Vitest to Deno's native test runner - -#### Current Test Setup (Vitest) - -```javascript -// tests/Tea_App.test.js -import { describe, test, expect } from 'vitest'; -import { TeaApp } from '../lib/es6/src/tea/Tea_App.res.js'; - -describe('Tea_App', () => { - test('should initialize app', () => { - // Test logic - }); -}); -``` - -#### Target Test Setup (Deno.test) - -```javascript -// tests/tea_app_test.ts -import { assertEquals, assertExists } from "jsr:@std/assert"; -import { TeaApp } from "../lib/es6/src/tea/Tea_App.res.js"; - -Deno.test("Tea_App - should initialize app", () => { - // Test logic using assertEquals/assertExists -}); - -Deno.test("Tea_App - should handle commands", () => { - // Test logic -}); -``` - -#### Migration Steps - -1. **Convert test files:** - - Rename `tests/*.test.js` → `tests/*_test.ts` - - Replace Vitest imports with `jsr:@std/assert` - - Replace `describe()` + `test()` with flat `Deno.test()` - - Replace `expect().toBe()` with `assertEquals()` - -2. **Update deno.json:** - ```json - { - "tasks": { - "test": "deno test --allow-read --allow-env tests/", - "test:watch": "deno test --watch --allow-read --allow-env tests/", - "test:coverage": "deno test --coverage=coverage/ tests/ && deno coverage coverage/" - } - } - ``` - -3. **Remove Vitest from package.json:** - - Remove `vitest`, `@vitest/ui`, `@vitest/coverage-v8`, `happy-dom` - -4. **Update npm scripts in package.json:** - - Remove `"test": "vitest run"` - - Remove `"test:watch": "vitest"` - - Remove `"test:ui": "vitest --ui"` - - Remove `"test:coverage": "vitest run --coverage"` - -5. **Update CI/CD workflows** (`.github/workflows/*.yml`): - - Replace `npm run test` with `deno task test` - -6. **Update PLAYBOOK.scm:** - - Document new Deno test commands - - Update testing procedures - -**Impact:** Removes 4 npm dependencies (vitest, @vitest/ui, @vitest/coverage-v8, happy-dom) - ---- - -### Phase 3: Minimize npm to ReScript Only ✅ (Ready Now) - -**Goal:** Keep npm ONLY for ReScript compilation - -#### Final package.json (Minimal) - -```json -{ - "name": "panll", - "version": "0.1.0", - "type": "module", - "scripts": { - "res:build": "rescript build", - "res:watch": "rescript build -w", - "res:clean": "rescript clean" - }, - "devDependencies": { - "rescript": "^11.1.4", - "@rescript/core": "^1.6.1" - }, - "dependencies": { - "rescript-webapi": "^0.10.0" - } -} -``` - -#### Final deno.json (Primary) - -```json -{ - "name": "@hyperpolymath/panll", - "version": "0.1.0", - "permissions": { - "read": true, - "write": ["./public", "./coverage"], - "run": true, - "env": true - }, - "tasks": { - "dev": "deno task css:watch & tauri dev", - "build": "deno task css:build && tauri build", - "css:build": "deno run -A npm:tailwindcss@4.1.18 -i ./src/styles/input.css -o ./public/styles.css --minify", - "css:watch": "deno run -A npm:tailwindcss@4.1.18 -i ./src/styles/input.css -o ./public/styles.css --watch", - "test": "deno test --allow-read --allow-env tests/", - "test:watch": "deno test --watch --allow-read --allow-env tests/", - "test:coverage": "deno test --coverage=coverage/ tests/ && deno coverage coverage/", - "lint": "deno lint src/ tests/", - "fmt": "deno fmt src/ tests/" - }, - "imports": { - "@std/": "jsr:@std/", - "@std/assert": "jsr:@std/assert@^1.0.0" - }, - "compilerOptions": { - "strict": true, - "noImplicitAny": true - } -} -``` - -**Impact:** npm usage reduced to 3 packages (ReScript only), all other tasks via Deno - ---- - -## Implementation Plan - -### Step 1: Backup Current Setup ✅ - -```bash -git checkout -b feature/npm-to-deno-migration -git add -A -git commit -m "chore: checkpoint before npm→Deno migration" -``` - -### Step 2: Phase 1 - Eliminate Tauri CLI npm ✅ - -```bash -# Install Tauri CLI via Cargo -cargo install tauri-cli - -# Verify installation -tauri --version # Should show "tauri-cli 2.x.x" - -# Update deno.json (already uses `tauri` command, no changes needed) - -# Remove from package.json -npm uninstall @tauri-apps/cli - -# Test -deno task dev # Should work with global tauri -``` - -### Step 3: Phase 2 - Migrate Tests to Deno ✅ - -```bash -# Convert test files (manual or script-assisted) -# Example: tests/Tea_App.test.js → tests/tea_app_test.ts - -# Update imports and assertions -# Vitest → @std/assert - -# Remove Vitest from package.json -npm uninstall vitest @vitest/ui @vitest/coverage-v8 happy-dom - -# Update deno.json with test tasks (see Phase 2 above) - -# Run tests -deno task test # Should pass (33 tests) - -# Generate coverage -deno task test:coverage -``` - -### Step 4: Phase 3 - Finalize Migration ✅ - -```bash -# Verify package.json contains only ReScript deps - -# Update README.adoc with new commands: -# - npm run res:build (ReScript compilation) -# - deno task dev (Tauri + Tailwind) -# - deno task test (Deno tests) - -# Update PLAYBOOK.scm with new procedures - -# Commit -git add -A -git commit -m "feat: migrate to Deno-primary build system (npm for ReScript only)" -``` - -### Step 5: Update Documentation ✅ - -Files to update: -- [x] `README.adoc` - Build commands, prerequisites -- [x] `PLAYBOOK.scm` - Operational procedures, common commands -- [x] `STATE.scm` - Mark migration completed in work-completed -- [x] `.github/workflows/*.yml` - CI/CD commands (if any) - -### Step 6: Test Thoroughly ✅ - -```bash -# Clean slate -npm run res:clean -rm -rf node_modules coverage/ -npm install - -# Full build cycle -npm run res:build -deno task css:build -deno task dev # Verify app launches - -# Test suite -deno task test # Verify all tests pass -deno task test:coverage # Verify coverage meets target (87-91%) - -# Manual testing -# - Three panes render correctly -# - Keyboard shortcuts work (Ctrl+Shift+L/N/W) -# - No console errors -``` - ---- - -## Testing Strategy - -### Regression Testing - -- [x] All 33 tests converted and passing -- [x] Coverage maintained at 87-91%+ -- [x] App launches without errors -- [x] Three panes render correctly -- [x] Keyboard shortcuts functional -- [x] Tauri commands work (validate_inference, get_vexation_index) - -### Performance Testing - -- Compare build times: `npm` vs `deno task` -- Verify hot reload still works with Deno tasks -- Measure test execution time: Vitest vs Deno.test - ---- - -## Rollback Plan - -If migration fails: - -```bash -# Revert to checkpoint -git reset --hard HEAD~1 - -# Reinstall npm dependencies -npm install - -# Verify old system works -npm run test -deno task dev -``` - -Keep migration branch for future attempts. - ---- - -## Future: Full npm Elimination - -### Blocker: ReScript Deno Support - -**Current:** ReScript compiler built on Node.js, no Deno support -**Tracking:** https://github.com/rescript-lang/rescript-compiler/issues/ - -**When ReScript supports Deno:** - -1. Remove `package.json` entirely -2. Move ReScript compilation to `deno.json`: - ```json - { - "tasks": { - "res:build": "deno run -A jsr:@rescript/compiler build", - "res:watch": "deno run -A jsr:@rescript/compiler build -w" - } - } - ``` -3. Update `rescript.json` to use Deno paths -4. Remove `node_modules/` from `.gitignore` -5. Document in PLAYBOOK.scm - -**Alternative:** If ReScript never supports Deno, consider: -- Migrating to Gleam (compiles to JS, Deno-compatible) -- Migrating to PureScript (Deno-compatible) -- Staying with minimal npm (acceptable compromise) - ---- - -## Benefits of Migration - -### Policy Compliance ✅ - -- Follows hyperpolymath Deno-first policy -- Reduces npm surface area from 9 deps → 3 deps -- Clear separation: npm = ReScript only, Deno = everything else - -### Developer Experience 📈 - -- Fewer package managers (Deno primary, npm minimal) -- Faster installs (Deno caches jsr/npm imports) -- Native test runner (no Vitest config) -- Better error messages (Deno's stack traces) - -### Performance 🚀 - -- Deno.test faster than Vitest (no transpilation) -- Tailwind via Deno faster (no npm overhead) -- Smaller node_modules (only ReScript deps) - -### Security 🔒 - -- Deno explicit permissions (--allow-read, --allow-run) -- Fewer npm dependencies = smaller attack surface -- cargo-installed Tauri CLI (no npm supply chain risk) - ---- - -## Open Questions - -1. **Coverage reporting:** Deno coverage format compatible with CI/CD? -2. **Test UI:** Vitest UI useful - Deno equivalent? -3. **ReScript timeline:** When (if ever) will ReScript support Deno? -4. **Breaking changes:** Does migration break any workflows? - ---- - -## Success Criteria - -- [x] `package.json` contains ≤3 dependencies (ReScript ecosystem only) -- [x] All build tasks run via `deno task` (except ReScript compilation) -- [x] All tests pass with `deno test` -- [x] Coverage ≥87% maintained -- [x] App launches and functions correctly -- [x] Documentation updated (README, PLAYBOOK) -- [x] Migration completed within 1-2 weeks - ---- - -**Status:** Ready for implementation -**Assignee:** TBD -**Estimated Effort:** 3-5 days (Phase 1-3) -**Risk Level:** Low (incremental migration, rollback available) - ---- - -## Related Documents - -- `MIGRATION-TO-RESCRIPT-TEA.md` - TEA library migration -- `PLAYBOOK.scm` - Operational procedures -- `STATE.scm` - Project state and blockers -- `~/.claude/CLAUDE.md` - Hyperpolymath language policy diff --git a/docs/archive/RESCRIPT-TEA-MIGRATION-GUIDE.adoc b/docs/archive/RESCRIPT-TEA-MIGRATION-GUIDE.adoc new file mode 100644 index 00000000..c8a403c4 --- /dev/null +++ b/docs/archive/RESCRIPT-TEA-MIGRATION-GUIDE.adoc @@ -0,0 +1,615 @@ +== ReScript TEA Migration Guide: Custom → Official (rescript-tea@0.16.0) + +=== ⛔ SUPERSEDED — DO NOT FOLLOW + +*Decision (2026-03-08):* The custom TEA in `+src/tea/+` is PanLL’s +permanent architecture. This migration will not happen. See +`+docs/TEA_GUIDE.md+` §Permanence Decision for rationale. + +*Status:* CANCELLED *Risk Level:* N/A *Estimated Effort:* N/A +*Requires:* N/A + +''''' + +=== Current Status ⚠️ + +*IMPORTANT:* The MIGRATION-TO-RESCRIPT-TEA.md checklist is incorrect! + +* ❌ rescript-tea@0.16.0 is *NOT installed* (not in package.json or +node_modules) +* ✅ Custom TEA implementation in `+src/tea/+` is *fully functional* (33 +tests passing) +* ✅ Draft "`New`" files exist (AppNew.res, etc.) but *are not being +used* +* ✅ All modules use custom TEA APIs (Tea_App, Tea_Sub, Tea_Cmd, +Tea_Html, etc.) + +*Recommendation:* Do NOT start this migration until: 1. v0.1.0 milestone +complete 2. Full test coverage (95%+) for custom TEA 3. Comprehensive +migration test plan ready 4. Backup/rollback plan in place + +''''' + +=== Why Migrate? + +==== Benefits of Official rescript-tea + +[arabic] +. *Battle-tested* - Used by Darklang and other production apps +. *More features* - Navigation, HTTP, Time, Mouse, AnimationFrame, +Random, Debug +. *Community support* - Issues, PRs, updates, documentation +. *Less maintenance* - No need to maintain custom TEA runtime +. *Better performance* - Optimized virtual DOM diffing +. *Documentation* - Follows Elm’s well-documented architecture + +==== Costs of Migration + +[arabic] +. *High risk* - Core architecture change affects all modules +. *Time investment* - 1-2 weeks of focused work +. *Testing burden* - Need to re-test everything +. *Potential bugs* - API differences may introduce regressions +. *No keyboard subscriptions* - rescript-tea doesn’t have built-in +keyboard support (need custom) + +''''' + +=== Pre-Migration Checklist + +Before starting migration, ensure: + +* [ ] All 33 tests passing with custom TEA +* [ ] Test coverage ≥95% (currently 87-91%) +* [ ] All features documented and working +* [ ] Git branch created: +`+git checkout -b feature/migrate-to-official-rescript-tea+` +* [ ] Backup created: `+git tag pre-rescript-tea-migration+` +* [ ] Team approval obtained (if applicable) +* [ ] User stories written for all features to preserve +* [ ] Performance baseline measured (render time, update time) + +''''' + +=== Migration Plan: 6 Phases + +==== Phase 0: Install rescript-tea ✅ (30 minutes) + +[source,bash] +---- +# Install official rescript-tea package +npm install rescript-tea@0.16.0 + +# Update rescript.json to include rescript-tea +# Add to bs-dependencies: ["rescript-tea"] + +# Verify installation +ls node_modules/rescript-tea/ # Should see src/ directory + +# Check available modules +ls node_modules/rescript-tea/src/*.res +# Expected: tea_app.res, tea_cmd.res, tea_sub.res, tea_html.res, etc. +---- + +*Verify:* `+npm list rescript-tea+` shows `+rescript-tea@0.16.0+` + +''''' + +==== Phase 1: Create Custom Subscriptions ✅ (1-2 days) + +*Problem:* Official rescript-tea has no built-in keyboard subscriptions. + +*Solution:* Create custom keyboard subscription using +Tea_Sub.registration. + +===== Step 1.1: Create `+src/subscriptions/KeyboardV2.res+` + +[source,rescript] +---- +// SPDX-License-Identifier: CC-BY-SA-4.0 +// Custom keyboard subscription for rescript-tea + +module KeyboardV2 = { + type keyEvent = { + key: string, + ctrlKey: bool, + shiftKey: bool, + altKey: bool, + metaKey: bool, + } + + // External bindings to browser addEventListener/removeEventListener + @val @scope("window") + external addEventListener: (string, Dom.event => unit) => unit = "addEventListener" + + @val @scope("window") + external removeEventListener: (string, Dom.event => unit) => unit = "removeEventListener" + + // Extract key event data from DOM event + let extractKeyEvent = (evt: Dom.event): keyEvent => { + open Webapi.Dom + let keyboardEvt = evt->KeyboardEvent.fromEvent + switch keyboardEvt { + | Some(ke) => { + key: ke->KeyboardEvent.key, + ctrlKey: ke->KeyboardEvent.ctrlKey, + shiftKey: ke->KeyboardEvent.shiftKey, + altKey: ke->KeyboardEvent.altKey, + metaKey: ke->KeyboardEvent.metaKey, + } + | None => { + key: "", + ctrlKey: false, + shiftKey: false, + altKey: false, + metaKey: false, + } + } + } + + // Create keyboard subscription using Tea_Sub.registration + let onKeyDown = (tagger: keyEvent => 'msg): Tea_Sub.t<'msg> => { + Tea_Sub.registration( + "keyboard-keydown", + enabler => { + // Handler function that extracts event and calls tagger + let handler = evt => { + let keyEvent = extractKeyEvent(evt) + enabler(tagger(keyEvent)) + } + + // Subscribe to keydown events + addEventListener("keydown", handler) + + // Return cleanup function + () => removeEventListener("keydown", handler) + } + ) + } + + let onKeyUp = (tagger: keyEvent => 'msg): Tea_Sub.t<'msg> => { + Tea_Sub.registration( + "keyboard-keyup", + enabler => { + let handler = evt => { + let keyEvent = extractKeyEvent(evt) + enabler(tagger(keyEvent)) + } + addEventListener("keyup", handler) + () => removeEventListener("keyup", handler) + } + ) + } +} +---- + +===== Step 1.2: Test KeyboardV2 + +[source,rescript] +---- +// tests/keyboard_v2_test.ts (Deno test after npm→Deno migration) +// Or tests/KeyboardV2.test.js (Vitest for now) + +import { test, expect } from 'vitest'; +// Test keyboard subscription creation +// (Manual testing in browser required for actual key events) +---- + +''''' + +==== Phase 2: Create Custom Tauri Commands ✅ (1-2 days) + +*Problem:* Official rescript-tea doesn’t know about Tauri. + +*Solution:* Wrap Tauri invoke calls in Tea_Cmd.call. + +===== Step 2.1: Create `+src/commands/TauriCmdV2.res+` + +[source,rescript] +---- +// SPDX-License-Identifier: CC-BY-SA-4.0 +// Tauri commands wrapped for rescript-tea + +module TauriCmdV2 = { + // External binding to Tauri invoke + @module("@tauri-apps/api/core") + external invoke: (string, 'payload) => promise<'result> = "invoke" + + // Validate inference token against constraints + let validateInference = ( + token: string, + constraints: array, + tagger: result => 'msg + ): Tea_Cmd.t<'msg> => { + Tea_Cmd.call(callbacks => { + // Call Tauri backend + invoke("validate_inference", {"token": token, "constraints": constraints}) + ->Promise.then(result => { + // Enqueue success message + callbacks.enqueue(tagger(Ok(result))) + Promise.resolve() + }) + ->Promise.catch(err => { + // Enqueue error message + callbacks.enqueue(tagger(Error("Validation failed"))) + Promise.resolve() + }) + ->ignore + }) + } + + // Get vexation index from backend + let getVexationIndex = (tagger: float => 'msg): Tea_Cmd.t<'msg> => { + Tea_Cmd.call(callbacks => { + invoke("get_vexation_index", ()) + ->Promise.then(index => { + callbacks.enqueue(tagger(index)) + Promise.resolve() + }) + ->Promise.catch(_err => { + // Default to 0.0 on error + callbacks.enqueue(tagger(0.0)) + Promise.resolve() + }) + ->ignore + }) + } + + // Submit feedback to backend + let submitFeedback = ( + paneLState: string, + paneNState: string, + paneWState: string, + reportType: string, + tagger: result => 'msg + ): Tea_Cmd.t<'msg> => { + Tea_Cmd.call(callbacks => { + let payload = { + "pane_l_state": paneLState, + "pane_n_state": paneNState, + "pane_w_state": paneWState, + "report_type": reportType, + } + invoke("submit_feedback", payload) + ->Promise.then(response => { + callbacks.enqueue(tagger(Ok(response))) + Promise.resolve() + }) + ->Promise.catch(_err => { + callbacks.enqueue(tagger(Error("Feedback submission failed"))) + Promise.resolve() + }) + ->ignore + }) + } +} +---- + +===== Step 2.2: Test Tauri Commands + +[source,javascript] +---- +// tests/tauri_cmd_v2_test.ts +// Integration test with Tauri backend (requires Tauri dev running) +---- + +''''' + +==== Phase 3: Update Module Imports ✅ (2-3 days) + +Update all source files to use official rescript-tea modules. + +===== Files to Update + +[arabic] +. `+src/App.res+` +. `+src/Update.res+` +. `+src/Subscriptions.res+` +. `+src/View.res+` (if uses Tea_Html) +. `+src/components/*.res+` (if use Tea_Html) + +===== Import Changes + +*Before (Custom TEA):* + +[source,rescript] +---- +// Imports come from src/tea/ +// (implicitly via rescript.json bsc-flags: -open Tea) +---- + +*After (Official rescript-tea):* + +[source,rescript] +---- +// src/App.res +open Tea_App // From rescript-tea package +open Tea_Cmd // From rescript-tea package + +// src/Subscriptions.res +open Tea_Sub // From rescript-tea package +open Tea_Time // From rescript-tea package +open Tea_Animationframe // From rescript-tea package +open KeyboardV2 // Our custom subscription + +// src/Update.res +open Tea_Cmd // From rescript-tea package +open TauriCmdV2 // Our custom Tauri commands +---- + +===== Step 3.1: Update `+src/App.res+` + +*Before:* + +[source,rescript] +---- +let main = Tea_App.standardProgram( + ~init, + ~update=Update.update, + ~view=View.view, + ~subscriptions=SubscriptionsFixed.all, + (), +) +---- + +*After:* + +[source,rescript] +---- +open Tea_App // Official rescript-tea + +let main = standardProgram( + ~init, + ~update=Update.update, + ~view=View.view, + ~subscriptions=Subscriptions.all, + (), +) +---- + +===== Step 3.2: Update `+src/Subscriptions.res+` + +Replace `+Keyboard.onKeyDown+` with `+KeyboardV2.onKeyDown+`. + +===== Step 3.3: Update `+src/Update.res+` + +Replace `+TauriCmd.*+` with `+TauriCmdV2.*+`. + +===== Step 3.4: Compile and Fix Errors + +[source,bash] +---- +npm run res:clean +npm run res:build + +# Fix compilation errors one by one +# Check error messages carefully - API differences may exist +---- + +''''' + +==== Phase 4: Update Tests ✅ (3-4 days) + +Re-test everything with official rescript-tea. + +===== Test Files to Update + +* `+tests/Tea_App.test.js+` +* `+tests/Tea_Cmd.test.js+` +* `+tests/Tea_Sub.test.js+` +* `+tests/Tea_Render.test.js+` + +===== Changes Needed + +[arabic] +. Import from `+rescript-tea+` package instead of custom `+src/tea/+` +. Update expectations for API differences +. Add tests for KeyboardV2 and TauriCmdV2 +. Test integration: keyboard → update → view cycle + +===== Run Tests + +[source,bash] +---- +npm run test # Should see 33 passing tests (at minimum) +npm run test:coverage # Coverage should be ≥87% +---- + +''''' + +==== Phase 5: Remove Custom TEA ✅ (1 day) + +Only after ALL tests passing and manual testing complete! + +[source,bash] +---- +# Backup first +git add -A +git commit -m "refactor: working with official rescript-tea (pre-cleanup)" + +# Remove custom TEA implementation +rm -rf src/tea/ + +# Remove draft "New" files (if not needed) +rm src/AppNew.res src/UpdateNew.res src/SubscriptionsFixed.res + +# Remove old files (if "New" files were renamed to replace them) +# (depends on your approach) + +# Compile +npm run res:build + +# Should compile without src/tea/ directory + +# Test +npm run test # Should still pass + +# Commit +git add -A +git commit -m "refactor: remove custom TEA implementation" +---- + +''''' + +==== Phase 6: Manual Testing & Validation ✅ (2-3 days) + +Comprehensive end-to-end testing. + +===== Test Scenarios + +[arabic] +. *App Startup* +* [ ] App launches without errors +* [ ] Three panes render correctly +* [ ] Dark Start mode displays Binary Star diagram +. *Pane Toggling* +* [ ] Ctrl+Shift+L toggles Pane-L +* [ ] Ctrl+Shift+N toggles Pane-N +* [ ] Ctrl+Shift+W toggles Pane-W +* [ ] Panes hide/show smoothly +. *Constraint Management* +* [ ] Can add constraint in Pane-L +* [ ] Can toggle constraint active/inactive +* [ ] Can pin constraint +* [ ] Can remove constraint +. *Neural Inference* +* [ ] Can trigger neural token generation +* [ ] Anti-Crash validation called +* [ ] Valid tokens pass to Pane-W +* [ ] Invalid tokens trigger intervention +. *Vexometer* +* [ ] Vexation index updates periodically +* [ ] Cancellations/corrections recorded +* [ ] Anti-inflammatory mode activates when vexation high +. *Performance* +* [ ] Render time acceptable (<100ms) +* [ ] Update time acceptable (<50ms) +* [ ] No memory leaks (check DevTools over 10 minutes) +. *Subscriptions* +* [ ] Keyboard events fire correctly +* [ ] Timer subscriptions work (vexation updates every 2s) +* [ ] Animation frame subscription works (orbital drift) + +===== Performance Baseline Comparison + +[cols=",,,",options="header",] +|=== +|Metric |Custom TEA |Official rescript-tea |Delta +|Initial render |? |? |? +|Update (avg) |? |? |? +|View render (avg) |? |? |? +|Memory usage (10 min) |? |? |? +|=== + +''''' + +=== Rollback Plan + +If migration fails: + +[source,bash] +---- +# Revert to pre-migration state +git checkout main +git branch -D feature/migrate-to-official-rescript-tea + +# Or revert to backup tag +git reset --hard pre-rescript-tea-migration + +# Reinstall dependencies +npm install +npm run res:build +npm run test +---- + +Keep custom TEA implementation until official migration proven stable. + +''''' + +=== Post-Migration Tasks + +After successful migration: + +* [ ] Update MIGRATION-TO-RESCRIPT-TEA.md (mark complete) +* [ ] Update STATE.scm (work-completed, completion-percentage) +* [ ] Update ROADMAP.adoc (v0.1.0 → v0.2.0) +* [ ] Update README.adoc (mention official rescript-tea) +* [ ] Update PLAYBOOK.scm (no changes to commands) +* [ ] Create GitHub release: v0.1.1 (patch with TEA migration) +* [ ] Announce migration in discussions +* [ ] Close migration-related issues + +''''' + +=== Risks & Mitigation + +[width="99%",cols="17%,21%,31%,31%",options="header",] +|=== +|Risk |Impact |Likelihood |Mitigation +|API differences break functionality |High |Medium |Thorough testing, +feature parity checklist + +|Performance regression |Medium |Low |Baseline comparison, profiling + +|Bugs in official rescript-tea |High |Low |Report upstream, keep custom +TEA as fallback + +|Test coverage gaps |Medium |Medium |Increase coverage to 95% before +migration + +|Time overrun (>2 weeks) |Medium |Medium |Time-box, defer non-critical +features +|=== + +''''' + +=== Decision: Defer or Proceed? + +==== Arguments for DEFER (Recommended) + +[arabic] +. *Custom TEA works perfectly* (33 tests passing, 87-91% coverage) +. *High risk, high effort* (1-2 weeks focused work) +. *v0.1.0 not complete yet* (other priorities) +. *No blocking bugs in custom TEA* +. *Official rescript-tea has no keyboard subscriptions* (need custom +anyway) + +==== Arguments for PROCEED + +[arabic] +. *Less maintenance long-term* (community maintains rescript-tea) +. *More features available* (HTTP, Navigation, Debug, etc.) +. *Better documentation* (Elm-style guides) +. *Community support* (issues, PRs) +. *Policy preference* (use existing libraries over custom) + +==== Recommendation + +*DEFER until v0.2.0 or later.* + +Focus on: - Completing v0.1.0 milestone (UI components, Tauri +integration) - Increasing test coverage to 95%+ - npm→Deno migration +(higher priority, lower risk) - Documenting custom TEA thoroughly (if +keeping long-term) + +Revisit after v0.2.0 when: - More features need official rescript-tea +(HTTP, Navigation) - Custom TEA maintenance burden increases - Team has +bandwidth for 2-week migration + +''''' + +=== Conclusion + +Migration from custom TEA to official rescript-tea is: - *Feasible* (API +similar, custom subscriptions possible) - *Risky* (core architecture +change) - *High effort* (1-2 weeks) - *Not urgent* (custom TEA works +fine) + +*Decision:* Defer until v0.2.0 or later. Document custom TEA thoroughly +for now. + +''''' + +*Last Updated:* 2026-02-07 *Maintainer:* Jonathan D.A. Jewell *Status:* +Migration guide complete, awaiting decision to proceed diff --git a/docs/archive/RESCRIPT-TEA-MIGRATION-GUIDE.md b/docs/archive/RESCRIPT-TEA-MIGRATION-GUIDE.md deleted file mode 100644 index 5d83e176..00000000 --- a/docs/archive/RESCRIPT-TEA-MIGRATION-GUIDE.md +++ /dev/null @@ -1,583 +0,0 @@ -# ReScript TEA Migration Guide: Custom → Official (rescript-tea@0.16.0) - -## ⛔ SUPERSEDED — DO NOT FOLLOW - -**Decision (2026-03-08):** The custom TEA in `src/tea/` is PanLL's permanent -architecture. This migration will not happen. See `docs/TEA_GUIDE.md` §Permanence -Decision for rationale. - -**Status:** CANCELLED -**Risk Level:** N/A -**Estimated Effort:** N/A -**Requires:** N/A - ---- - -## Current Status ⚠️ - -**IMPORTANT:** The MIGRATION-TO-RESCRIPT-TEA.md checklist is incorrect! - -- ❌ rescript-tea@0.16.0 is **NOT installed** (not in package.json or node_modules) -- ✅ Custom TEA implementation in `src/tea/` is **fully functional** (33 tests passing) -- ✅ Draft "New" files exist (AppNew.res, etc.) but **are not being used** -- ✅ All modules use custom TEA APIs (Tea_App, Tea_Sub, Tea_Cmd, Tea_Html, etc.) - -**Recommendation:** Do NOT start this migration until: -1. v0.1.0 milestone complete -2. Full test coverage (95%+) for custom TEA -3. Comprehensive migration test plan ready -4. Backup/rollback plan in place - ---- - -## Why Migrate? - -### Benefits of Official rescript-tea - -1. **Battle-tested** - Used by Darklang and other production apps -2. **More features** - Navigation, HTTP, Time, Mouse, AnimationFrame, Random, Debug -3. **Community support** - Issues, PRs, updates, documentation -4. **Less maintenance** - No need to maintain custom TEA runtime -5. **Better performance** - Optimized virtual DOM diffing -6. **Documentation** - Follows Elm's well-documented architecture - -### Costs of Migration - -1. **High risk** - Core architecture change affects all modules -2. **Time investment** - 1-2 weeks of focused work -3. **Testing burden** - Need to re-test everything -4. **Potential bugs** - API differences may introduce regressions -5. **No keyboard subscriptions** - rescript-tea doesn't have built-in keyboard support (need custom) - ---- - -## Pre-Migration Checklist - -Before starting migration, ensure: - -- [ ] All 33 tests passing with custom TEA -- [ ] Test coverage ≥95% (currently 87-91%) -- [ ] All features documented and working -- [ ] Git branch created: `git checkout -b feature/migrate-to-official-rescript-tea` -- [ ] Backup created: `git tag pre-rescript-tea-migration` -- [ ] Team approval obtained (if applicable) -- [ ] User stories written for all features to preserve -- [ ] Performance baseline measured (render time, update time) - ---- - -## Migration Plan: 6 Phases - -### Phase 0: Install rescript-tea ✅ (30 minutes) - -```bash -# Install official rescript-tea package -npm install rescript-tea@0.16.0 - -# Update rescript.json to include rescript-tea -# Add to bs-dependencies: ["rescript-tea"] - -# Verify installation -ls node_modules/rescript-tea/ # Should see src/ directory - -# Check available modules -ls node_modules/rescript-tea/src/*.res -# Expected: tea_app.res, tea_cmd.res, tea_sub.res, tea_html.res, etc. -``` - -**Verify:** `npm list rescript-tea` shows `rescript-tea@0.16.0` - ---- - -### Phase 1: Create Custom Subscriptions ✅ (1-2 days) - -**Problem:** Official rescript-tea has no built-in keyboard subscriptions. - -**Solution:** Create custom keyboard subscription using Tea_Sub.registration. - -#### Step 1.1: Create `src/subscriptions/KeyboardV2.res` - -```rescript -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Custom keyboard subscription for rescript-tea - -module KeyboardV2 = { - type keyEvent = { - key: string, - ctrlKey: bool, - shiftKey: bool, - altKey: bool, - metaKey: bool, - } - - // External bindings to browser addEventListener/removeEventListener - @val @scope("window") - external addEventListener: (string, Dom.event => unit) => unit = "addEventListener" - - @val @scope("window") - external removeEventListener: (string, Dom.event => unit) => unit = "removeEventListener" - - // Extract key event data from DOM event - let extractKeyEvent = (evt: Dom.event): keyEvent => { - open Webapi.Dom - let keyboardEvt = evt->KeyboardEvent.fromEvent - switch keyboardEvt { - | Some(ke) => { - key: ke->KeyboardEvent.key, - ctrlKey: ke->KeyboardEvent.ctrlKey, - shiftKey: ke->KeyboardEvent.shiftKey, - altKey: ke->KeyboardEvent.altKey, - metaKey: ke->KeyboardEvent.metaKey, - } - | None => { - key: "", - ctrlKey: false, - shiftKey: false, - altKey: false, - metaKey: false, - } - } - } - - // Create keyboard subscription using Tea_Sub.registration - let onKeyDown = (tagger: keyEvent => 'msg): Tea_Sub.t<'msg> => { - Tea_Sub.registration( - "keyboard-keydown", - enabler => { - // Handler function that extracts event and calls tagger - let handler = evt => { - let keyEvent = extractKeyEvent(evt) - enabler(tagger(keyEvent)) - } - - // Subscribe to keydown events - addEventListener("keydown", handler) - - // Return cleanup function - () => removeEventListener("keydown", handler) - } - ) - } - - let onKeyUp = (tagger: keyEvent => 'msg): Tea_Sub.t<'msg> => { - Tea_Sub.registration( - "keyboard-keyup", - enabler => { - let handler = evt => { - let keyEvent = extractKeyEvent(evt) - enabler(tagger(keyEvent)) - } - addEventListener("keyup", handler) - () => removeEventListener("keyup", handler) - } - ) - } -} -``` - -#### Step 1.2: Test KeyboardV2 - -```rescript -// tests/keyboard_v2_test.ts (Deno test after npm→Deno migration) -// Or tests/KeyboardV2.test.js (Vitest for now) - -import { test, expect } from 'vitest'; -// Test keyboard subscription creation -// (Manual testing in browser required for actual key events) -``` - ---- - -### Phase 2: Create Custom Tauri Commands ✅ (1-2 days) - -**Problem:** Official rescript-tea doesn't know about Tauri. - -**Solution:** Wrap Tauri invoke calls in Tea_Cmd.call. - -#### Step 2.1: Create `src/commands/TauriCmdV2.res` - -```rescript -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Tauri commands wrapped for rescript-tea - -module TauriCmdV2 = { - // External binding to Tauri invoke - @module("@tauri-apps/api/core") - external invoke: (string, 'payload) => promise<'result> = "invoke" - - // Validate inference token against constraints - let validateInference = ( - token: string, - constraints: array, - tagger: result => 'msg - ): Tea_Cmd.t<'msg> => { - Tea_Cmd.call(callbacks => { - // Call Tauri backend - invoke("validate_inference", {"token": token, "constraints": constraints}) - ->Promise.then(result => { - // Enqueue success message - callbacks.enqueue(tagger(Ok(result))) - Promise.resolve() - }) - ->Promise.catch(err => { - // Enqueue error message - callbacks.enqueue(tagger(Error("Validation failed"))) - Promise.resolve() - }) - ->ignore - }) - } - - // Get vexation index from backend - let getVexationIndex = (tagger: float => 'msg): Tea_Cmd.t<'msg> => { - Tea_Cmd.call(callbacks => { - invoke("get_vexation_index", ()) - ->Promise.then(index => { - callbacks.enqueue(tagger(index)) - Promise.resolve() - }) - ->Promise.catch(_err => { - // Default to 0.0 on error - callbacks.enqueue(tagger(0.0)) - Promise.resolve() - }) - ->ignore - }) - } - - // Submit feedback to backend - let submitFeedback = ( - paneLState: string, - paneNState: string, - paneWState: string, - reportType: string, - tagger: result => 'msg - ): Tea_Cmd.t<'msg> => { - Tea_Cmd.call(callbacks => { - let payload = { - "pane_l_state": paneLState, - "pane_n_state": paneNState, - "pane_w_state": paneWState, - "report_type": reportType, - } - invoke("submit_feedback", payload) - ->Promise.then(response => { - callbacks.enqueue(tagger(Ok(response))) - Promise.resolve() - }) - ->Promise.catch(_err => { - callbacks.enqueue(tagger(Error("Feedback submission failed"))) - Promise.resolve() - }) - ->ignore - }) - } -} -``` - -#### Step 2.2: Test Tauri Commands - -```javascript -// tests/tauri_cmd_v2_test.ts -// Integration test with Tauri backend (requires Tauri dev running) -``` - ---- - -### Phase 3: Update Module Imports ✅ (2-3 days) - -Update all source files to use official rescript-tea modules. - -#### Files to Update - -1. `src/App.res` -2. `src/Update.res` -3. `src/Subscriptions.res` -4. `src/View.res` (if uses Tea_Html) -5. `src/components/*.res` (if use Tea_Html) - -#### Import Changes - -**Before (Custom TEA):** -```rescript -// Imports come from src/tea/ -// (implicitly via rescript.json bsc-flags: -open Tea) -``` - -**After (Official rescript-tea):** -```rescript -// src/App.res -open Tea_App // From rescript-tea package -open Tea_Cmd // From rescript-tea package - -// src/Subscriptions.res -open Tea_Sub // From rescript-tea package -open Tea_Time // From rescript-tea package -open Tea_Animationframe // From rescript-tea package -open KeyboardV2 // Our custom subscription - -// src/Update.res -open Tea_Cmd // From rescript-tea package -open TauriCmdV2 // Our custom Tauri commands -``` - -#### Step 3.1: Update `src/App.res` - -**Before:** -```rescript -let main = Tea_App.standardProgram( - ~init, - ~update=Update.update, - ~view=View.view, - ~subscriptions=SubscriptionsFixed.all, - (), -) -``` - -**After:** -```rescript -open Tea_App // Official rescript-tea - -let main = standardProgram( - ~init, - ~update=Update.update, - ~view=View.view, - ~subscriptions=Subscriptions.all, - (), -) -``` - -#### Step 3.2: Update `src/Subscriptions.res` - -Replace `Keyboard.onKeyDown` with `KeyboardV2.onKeyDown`. - -#### Step 3.3: Update `src/Update.res` - -Replace `TauriCmd.*` with `TauriCmdV2.*`. - -#### Step 3.4: Compile and Fix Errors - -```bash -npm run res:clean -npm run res:build - -# Fix compilation errors one by one -# Check error messages carefully - API differences may exist -``` - ---- - -### Phase 4: Update Tests ✅ (3-4 days) - -Re-test everything with official rescript-tea. - -#### Test Files to Update - -- `tests/Tea_App.test.js` -- `tests/Tea_Cmd.test.js` -- `tests/Tea_Sub.test.js` -- `tests/Tea_Render.test.js` - -#### Changes Needed - -1. Import from `rescript-tea` package instead of custom `src/tea/` -2. Update expectations for API differences -3. Add tests for KeyboardV2 and TauriCmdV2 -4. Test integration: keyboard → update → view cycle - -#### Run Tests - -```bash -npm run test # Should see 33 passing tests (at minimum) -npm run test:coverage # Coverage should be ≥87% -``` - ---- - -### Phase 5: Remove Custom TEA ✅ (1 day) - -Only after ALL tests passing and manual testing complete! - -```bash -# Backup first -git add -A -git commit -m "refactor: working with official rescript-tea (pre-cleanup)" - -# Remove custom TEA implementation -rm -rf src/tea/ - -# Remove draft "New" files (if not needed) -rm src/AppNew.res src/UpdateNew.res src/SubscriptionsFixed.res - -# Remove old files (if "New" files were renamed to replace them) -# (depends on your approach) - -# Compile -npm run res:build - -# Should compile without src/tea/ directory - -# Test -npm run test # Should still pass - -# Commit -git add -A -git commit -m "refactor: remove custom TEA implementation" -``` - ---- - -### Phase 6: Manual Testing & Validation ✅ (2-3 days) - -Comprehensive end-to-end testing. - -#### Test Scenarios - -1. **App Startup** - - [ ] App launches without errors - - [ ] Three panes render correctly - - [ ] Dark Start mode displays Binary Star diagram - -2. **Pane Toggling** - - [ ] Ctrl+Shift+L toggles Pane-L - - [ ] Ctrl+Shift+N toggles Pane-N - - [ ] Ctrl+Shift+W toggles Pane-W - - [ ] Panes hide/show smoothly - -3. **Constraint Management** - - [ ] Can add constraint in Pane-L - - [ ] Can toggle constraint active/inactive - - [ ] Can pin constraint - - [ ] Can remove constraint - -4. **Neural Inference** - - [ ] Can trigger neural token generation - - [ ] Anti-Crash validation called - - [ ] Valid tokens pass to Pane-W - - [ ] Invalid tokens trigger intervention - -5. **Vexometer** - - [ ] Vexation index updates periodically - - [ ] Cancellations/corrections recorded - - [ ] Anti-inflammatory mode activates when vexation high - -6. **Performance** - - [ ] Render time acceptable (<100ms) - - [ ] Update time acceptable (<50ms) - - [ ] No memory leaks (check DevTools over 10 minutes) - -7. **Subscriptions** - - [ ] Keyboard events fire correctly - - [ ] Timer subscriptions work (vexation updates every 2s) - - [ ] Animation frame subscription works (orbital drift) - -#### Performance Baseline Comparison - -| Metric | Custom TEA | Official rescript-tea | Delta | -|--------|------------|----------------------|-------| -| Initial render | ? | ? | ? | -| Update (avg) | ? | ? | ? | -| View render (avg) | ? | ? | ? | -| Memory usage (10 min) | ? | ? | ? | - ---- - -## Rollback Plan - -If migration fails: - -```bash -# Revert to pre-migration state -git checkout main -git branch -D feature/migrate-to-official-rescript-tea - -# Or revert to backup tag -git reset --hard pre-rescript-tea-migration - -# Reinstall dependencies -npm install -npm run res:build -npm run test -``` - -Keep custom TEA implementation until official migration proven stable. - ---- - -## Post-Migration Tasks - -After successful migration: - -- [ ] Update MIGRATION-TO-RESCRIPT-TEA.md (mark complete) -- [ ] Update STATE.scm (work-completed, completion-percentage) -- [ ] Update ROADMAP.adoc (v0.1.0 → v0.2.0) -- [ ] Update README.adoc (mention official rescript-tea) -- [ ] Update PLAYBOOK.scm (no changes to commands) -- [ ] Create GitHub release: v0.1.1 (patch with TEA migration) -- [ ] Announce migration in discussions -- [ ] Close migration-related issues - ---- - -## Risks & Mitigation - -| Risk | Impact | Likelihood | Mitigation | -|------|--------|------------|------------| -| API differences break functionality | High | Medium | Thorough testing, feature parity checklist | -| Performance regression | Medium | Low | Baseline comparison, profiling | -| Bugs in official rescript-tea | High | Low | Report upstream, keep custom TEA as fallback | -| Test coverage gaps | Medium | Medium | Increase coverage to 95% before migration | -| Time overrun (>2 weeks) | Medium | Medium | Time-box, defer non-critical features | - ---- - -## Decision: Defer or Proceed? - -### Arguments for DEFER (Recommended) - -1. **Custom TEA works perfectly** (33 tests passing, 87-91% coverage) -2. **High risk, high effort** (1-2 weeks focused work) -3. **v0.1.0 not complete yet** (other priorities) -4. **No blocking bugs in custom TEA** -5. **Official rescript-tea has no keyboard subscriptions** (need custom anyway) - -### Arguments for PROCEED - -1. **Less maintenance long-term** (community maintains rescript-tea) -2. **More features available** (HTTP, Navigation, Debug, etc.) -3. **Better documentation** (Elm-style guides) -4. **Community support** (issues, PRs) -5. **Policy preference** (use existing libraries over custom) - -### Recommendation - -**DEFER until v0.2.0 or later.** - -Focus on: -- Completing v0.1.0 milestone (UI components, Tauri integration) -- Increasing test coverage to 95%+ -- npm→Deno migration (higher priority, lower risk) -- Documenting custom TEA thoroughly (if keeping long-term) - -Revisit after v0.2.0 when: -- More features need official rescript-tea (HTTP, Navigation) -- Custom TEA maintenance burden increases -- Team has bandwidth for 2-week migration - ---- - -## Conclusion - -Migration from custom TEA to official rescript-tea is: -- **Feasible** (API similar, custom subscriptions possible) -- **Risky** (core architecture change) -- **High effort** (1-2 weeks) -- **Not urgent** (custom TEA works fine) - -**Decision:** Defer until v0.2.0 or later. Document custom TEA thoroughly for now. - ---- - -**Last Updated:** 2026-02-07 -**Maintainer:** Jonathan D.A. Jewell -**Status:** Migration guide complete, awaiting decision to proceed diff --git a/docs/archive/ROADMAP.adoc b/docs/archive/ROADMAP.adoc new file mode 100644 index 00000000..971196a3 --- /dev/null +++ b/docs/archive/ROADMAP.adoc @@ -0,0 +1,357 @@ +== PanLL Roadmap + +*Last updated: 2026-03-02* *CRG Grade: D (Alpha Preview)* + +PanLL is the reference implementation of the eNSAID (embodied +NeuroSymbolic Accessibility-first Interface Design) specification. It +provides a unified mission control interface built on a three-panel +model (Panel-L constraints, Panel-N agent reasoning, Panel-W results) +with neurosymbolic intelligence behind each panel. This roadmap +documents where PanLL stands today, where it is going, and the +prioritised sprint plan to get there. + +''''' + +=== Current State + +* 14 panel UIs + 4 infrastructure layers, all compiling clean (0 +ReScript errors, 0 Rust errors) +* 107 ReScript files (26,798 lines) + 20 Rust files (5,342 lines) = 127 +source files, 32,140 lines +* Single TEA binary with unified panel switcher +* Pushed to GitHub: `+hyperpolymath/panll+` + +==== Built Panels (14) + +[width="100%",cols="8%,14%,17%,27%,34%",options="header",] +|=== +|# |Panel |Module |What It Does |Backend Status +|1 |Panel-L (Symbolic Mass) |PaneL |Constraints, rules, formal +specifications |Core (in-process) + +|2 |Panel-N (Neural Stream + ECHIDNA) |PaneN |AI reasoning, confidence, +theorem proving |Core (in-process) + +|3 |Panel-W (World/Barycentre + VeriSimDB) |PaneW |Results, dashboards, +live data, database tools |Core (in-process) + +|4 |VAB (Verified Assembly Building) |Vab |KSP-inspired server component +composer (111 proven-servers components) |UI only (no HTTP) + +|5 |CloudGuard |CloudGuard |Cloudflare domain security management |UI +only (needs Cloudflare API) + +|6 |Git-Private-Farm |Farm |Repo inventory (~265 repos), health scores, +Dependabot queue |UI only (needs local JSON read) + +|7 |Palimpsest Plaza |Plaza |PMPL licensing adoption, compliance audits, +signatures |UI only (needs filesystem scan) + +|8 |Reposystem |Reposystem |RSR compliance scores, template validation, +language policy |UI only (needs filesystem scan) + +|9 |Aerie |Aerie |Network diagnostics, speed tests, BGP forensics, proof +envelopes |UI only (needs V-lang API) + +|10 |Interfaces |Interfaces |Idris2 ABI inventory, Zig FFI build status, +binding coverage |UI only (needs filesystem scan) + +|11 |Playgrounds |Playgrounds |Multi-language code sandbox, NQC database +console, tutorials |UI only (needs NQC proxy) + +|12 |Hypatia |Hypatia |Neurosymbolic CI/CD: 5 neural nets, 298 repos, +safety triangle |UI only (needs Elixir API) + +|13 |Fleet (Gitbot-Fleet) |Fleet |6-bot orchestration dashboard, +findings, dispatch queue |UI only (needs Axum API) + +|14 |Minter (Panel Minter) |Minter |Create new panel modules with +accessibility by default |UI only (Rust backend exists) +|=== + +==== Infrastructure Layers (4) + +[width="99%",cols="20%,22%,36%,22%",options="header",] +|=== +|Layer |Module |What It Does |Status +|Panel Switcher |PanelSwitcher + PanelRegistry |Unified navigation bar +(replaces ad-hoc toggles) |Working + +|Provisioner |Provisioner + ProvisionerEngine |Portfolio bundles, +per-panel config, isolation tiers (Native/StandardPod/HardenedPod) |UI +complete, not wired to backends + +|Code Provenance Map |Provenance + ProvenanceEngine |Qubes-style trust +surface (git blame to semantic colours), accessibility palettes, hostile +UX |UI complete, needs git blame integration + +|Filesystem Watcher |Watcher + WatcherCmd |notify/inotify event feed +into TEA loop, all panels subscribe |Rust backend complete, needs +frontend event hookup +|=== + +==== Cognitive Governance (Always Present) + +These subsystems are embedded across the entire interface and are not +standalone panels. They represent the neurosymbolic intelligence layer +that makes PanLL more than a dashboard: + +* *Vexometer* – friction monitoring (cancellations, corrections, dwell +time) +* *Anti-Crash Gate* – circuit breaker between Panel-N and Panel-W +* *Orbital Drift Aura* – ambient visual indicator of system stability +* *Feedback-O-Tron* – feedback submission (expanding to opinion mining) +* *Information Humidity* – UI density adapts to cognitive load +(High/Medium/Low) +* *Dark Start* – intentional entry (architecture manifold on launch) + +''''' + +=== Roadmap Sprints + +==== Sprint 1 – "`Make It Breathe`" (Polish + First Run) + +Priority scoring: *C* = Complexity (1–5), *E* = Effort (sessions), *V* = +Value (1–5), *Score* = V / (C x E). Higher score means better return on +investment. + +[width="100%",cols="12%,15%,7%,7%,7%,18%,34%",options="header",] +|=== +|# |Item |C |E |V |Score |Description +|1 |Dark Start first-run polish |1 |1 |4 |4.00 |Auto-detect installed +backends, show connection status on launch, polish entry animation + +|2 |Tauri event wiring |2 |2 |5 |1.25 |Connect Watcher events to panel +refresh, panel switcher to backend lifecycle. Makes the app feel alive. + +|3 |Accessibility pass |2 |2 |4 |1.00 |Full keyboard nav, screen reader +testing, all 4 colour palettes verified. Essential before any public +showing. +|=== + +==== Sprint 2 – "`Make It Real`" (Backend Connections) + +[width="100%",cols="12%,15%,7%,7%,7%,18%,34%",options="header",] +|=== +|# |Item |C |E |V |Score |Description +|4 |Rust backend: Farm |2 |1 |4 |2.00 |Read +~/.git-private-farm/farm-manifest.json. Simplest backend – local JSON, +no HTTP. + +|5 |Rust backend: Fleet |2 |2 |4 |1.00 |reqwest to existing gitbot-fleet +Axum dashboard API (:8080). Has /api/health, /api/status, /api/findings. + +|6 |Provenance Map git-blame integration |3 |2 |4 |0.67 |Wire +ProvenanceCmd to actual git blame output parsing. Makes trust surface +real, not placeholder. + +|7 |Cross-panel bus (PanelBus) |2 |2 |3 |0.75 |Hypatia findings to Fleet +dispatch, Farm inventory to Reposystem scanning. Panels communicate. + +|8 |Feedback-O-Tron opinion mining |2 |2 |4 |1.00 |Aggregate feedback +signals across panels, sentiment tracking, friction heatmap. Feeds +Vexometer. +|=== + +==== Sprint 3 – "`Make It Complete`" (Remaining Backends) + +[width="100%",cols="12%,15%,7%,7%,7%,18%,34%",options="header",] +|=== +|# |Item |C |E |V |Score |Description +|9 |Rust backend: Hypatia |3 |3 |5 |0.56 |reqwest to Hypatia Elixir API. +Most important panel – 5 neural networks scanning 298 repos. + +|10 |Rust backend: Aerie |3 |2 |3 |0.50 |reqwest to V-lang API gateway +(GraphQL:4000, REST:4000). + +|11 |NQC console in Playgrounds |2 |2 |3 |0.75 |Wire existing NQC web UI +proxy (:4000) into Playgrounds panel. + +|12 |Rust backend: Reposystem + Plaza |2 |2 |3 |0.75 |Filesystem +scanning for .machine_readable/, editorconfig, Justfile, TOPOLOGY.md, +LICENSE. + +|13 |Provisioner install flow |3 |3 |4 |0.44 |Wire to Stapeln pod +creation, binary downloads, config persistence. +|=== + +==== Sprint 4 – "`Make It Extensible`" (Community Features) + +[width="100%",cols="12%,15%,7%,7%,7%,18%,34%",options="header",] +|=== +|# |Item |C |E |V |Score |Description +|14 |Odds & Sods (Package Manager) |3 |3 |3 |0.33 |New panel #15. +Unified Cargo/Gleam/Mix/Deno/asdf/Idris2/Zig view. The "`stuff that +doesn’t fit`" tracker. + +|15 |Stapeln pod integration |4 |4 |3 |0.19 |Real container lifecycle +for panel isolation tiers. Three defaults: no pod, Alpine+Podman, +Stapeln+Chainguard. + +|16 |Wharf (WordPress) |3 |3 |4 |0.44 |WP Wharf panel – Nickel configs, +Mooring Protocol, php-aegis. 43% of web runs WordPress. + +|17 |TypLL (Language Panel) |4 |5 |3 |0.15 |Core language development +panel for Eclexia/AffineScript/Anvomidav/Ephapax. + +|18 |Valence Shell integration |3 |3 |2 |0.22 |CLI tool switchable with +bash. Interesting for power users, not critical for Alpha. + +|19 |Micropatching + reversibility |4 |4 |2 |0.13 |Undo system for +config changes. Important eventually, deferred. +|=== + +==== Sprint 5 — "`Code MRI`" (Mutual Recognition & Integrity) + +Code MRI is the development transparency system — Turnitin for code, but +collaborative not adversarial. See DD-016 in DESIGN-DECISIONS.md. + +[width="100%",cols="12%,15%,7%,7%,7%,18%,34%",options="header",] +|=== +|# |Item |C |E |V |Score |Description +|20 |VoiceTag (Layer 0) |3 |2 |5 |0.83 |Voice/keyboard annotation on +code regions. Numbered tags, attribution, simple grammar. Entry point to +the full MRI system. (Also in Sprint 2 as it extends Provenance.) + +|21 |Blake3 Provenance Chain (Layer 1) |3 |3 |4 |0.44 |Tamper-resistant +attribution hashes per code region. Import/export carry provenance. + +|22 |VeriSimDB Development Timeline (Layer 2) |4 |4 |5 |0.31 +|Development-as-time-series. Timeline scrubber, snapshot rollback, "`end +credits`" documentary view. Dogfoods VeriSimDB. + +|23 |Pattern Diagnostics & Gamification (Layer 3) |3 |3 |4 |0.44 |AI +bullshit detector, efficiency patterns, victory conditions, badges. +Admin enforcement for education. + +|24 |Attribution-to-Licensing Link (Layer 4) |2 |2 |3 |0.75 +|Auto-generate PMPL/MPL attribution from provenance chains. +Machine-verifiable license compliance. + +|25 |Metrics & Learning Panel |3 |3 |4 |0.44 |ML-driven pattern +identification from Code MRI data. Recommends support for struggling +developers, suggests task reassignment based on strengths. Connects to +Hypatia’s neural networks for higher-order pattern detection. +|=== + +==== Future / Community Contributed + +* Game panels: Godot, Unity, Unreal Engine, IDApTIK level architect +* IDE integration: VSCode/VSCodium extension (export core as extension) +* Minecraft modding panel +* Statistease analytics panel +* eNSAID v1.0 specification publication + +''''' + +=== Version Milestones + +[width="100%",cols="31%,26%,23%,20%",options="header",] +|=== +|Version |Target |Focus |Gate +|v0.2.0-alpha |Q1 2026 |Sprint 1 complete, Dark Start polished, +accessibility verified |All keyboard nav works, screen reader tested + +|v0.3.0-alpha |Q2 2026 |Sprint 2 complete, Farm + Fleet backends live, +Provenance real |At least 2 backends return real data + +|v0.4.0-beta |Q3 2026 |Sprint 3 complete, Hypatia + Aerie live, NQC in +Playgrounds |5+ backends connected, cross-panel bus working + +|v0.5.0-beta |Q4 2026 |Sprint 4 started, Odds & Sods, Wharf, Stapeln +pods |Community contribution path documented + +|v0.6.0-beta |Q1 2027 |Sprint 5: Code MRI Layers 0-1 (VoiceTag + Blake3 +chain) |Voice annotation working, provenance tamper-resistant + +|v0.7.0-beta |Q2 2027 |Sprint 5: Code MRI Layers 2-4 (Timeline + +Diagnostics + Licensing) |VeriSimDB timeline scrubber, admin enforcement +mode + +|v1.0.0 |H2 2027 |eNSAID spec v1.0, all core panels CRG Grade B+, stable +API |Field-proven with real users +|=== + +''''' + +=== Component Readiness Grades (CRG) + +CRG is PanLL’s internal quality rubric. Every panel, infrastructure +layer, and cognitive governance subsystem receives a letter grade that +reflects its maturity. The grading system is deliberately strict: most +software would land at D or E on first release. + +[width="100%",cols="28%,34%,38%",options="header",] +|=== +|Grade |Meaning |Criteria +|X |Untested |No tests, no usage, unknown state + +|F |Harmful |Known bugs, security issues, actively dangerous + +|E |Minimal |Compiles, basic structure, stubs + +|D |Alpha |Feature-complete UI, compiles clean, not connected to real +backends + +|C |Beta |Connected to real backends, dogfooded by author + +|B |RC |Broadly validated, community tested, documented + +|A |Stable |Field-proven, formally verified where applicable, +production-ready +|=== + +*Current state:* All 14 panels are CRG Grade *D*. The four +infrastructure layers range from D to E depending on backend wiring. +Cognitive governance subsystems are Grade D (logic present, no +real-world signal yet). + +*Target for public showing:* At least Farm + Fleet at Grade *C* (real +data flowing, author-dogfooded). + +''''' + +=== Cross-Panel Communication Map + +The following data flows describe planned inter-panel communication via +the PanelBus (Sprint 2, item 7). Each arrow represents a typed message +channel. No panel directly imports another; all communication is +mediated by the bus. + +[width="100%",cols="22%,31%,26%,21%",options="header",] +|=== +|Source |Destination |Data Flow |Purpose +|Hypatia |Fleet |Scan findings with confidence |Fleet dispatch queue +receives prioritised work items + +|Farm |Reposystem |Repo inventory |Compliance scanning targets derived +from known repos + +|Farm |Hypatia |Repo list |Scanning targets for neurosymbolic CI/CD + +|Reposystem |Interfaces |Language bridges |Interface inventory updated +when language map changes + +|Databases |Playgrounds |Module configs |Playground gallery populated +from database profiles + +|Hypatia |Panel-N (core) |Neural confidence |Main reasoning display +reflects CI/CD scan confidence + +|Watcher |All panels |Filesystem events |Targeted refresh when monitored +files change on disk + +|Feedback-O-Tron |Vexometer |Sentiment signals |Friction index updated +from aggregated user feedback + +|Provenance |Anti-Crash Gate |Trust levels |Validation thresholds +adjusted based on code provenance + +|Provisioner |All panels |Isolation tier |Startup mode selection (native +vs. StandardPod vs. HardenedPod) +|=== + +''''' + +_This roadmap is maintained as a living document. Update as sprints +complete._ diff --git a/docs/archive/ROADMAP.md b/docs/archive/ROADMAP.md deleted file mode 100644 index 0aa1c825..00000000 --- a/docs/archive/ROADMAP.md +++ /dev/null @@ -1,179 +0,0 @@ - - -# PanLL Roadmap - -**Last updated: 2026-03-02** -**CRG Grade: D (Alpha Preview)** - -PanLL is the reference implementation of the eNSAID (embodied NeuroSymbolic Accessibility-first Interface Design) specification. It provides a unified mission control interface built on a three-panel model (Panel-L constraints, Panel-N agent reasoning, Panel-W results) with neurosymbolic intelligence behind each panel. This roadmap documents where PanLL stands today, where it is going, and the prioritised sprint plan to get there. - ---- - -## Current State - -- 14 panel UIs + 4 infrastructure layers, all compiling clean (0 ReScript errors, 0 Rust errors) -- 107 ReScript files (26,798 lines) + 20 Rust files (5,342 lines) = 127 source files, 32,140 lines -- Single TEA binary with unified panel switcher -- Pushed to GitHub: `hyperpolymath/panll` - -### Built Panels (14) - -| # | Panel | Module | What It Does | Backend Status | -|---|-------|--------|-------------|----------------| -| 1 | Panel-L (Symbolic Mass) | PaneL | Constraints, rules, formal specifications | Core (in-process) | -| 2 | Panel-N (Neural Stream + ECHIDNA) | PaneN | AI reasoning, confidence, theorem proving | Core (in-process) | -| 3 | Panel-W (World/Barycentre + VeriSimDB) | PaneW | Results, dashboards, live data, database tools | Core (in-process) | -| 4 | VAB (Verified Assembly Building) | Vab | KSP-inspired server component composer (111 proven-servers components) | UI only (no HTTP) | -| 5 | CloudGuard | CloudGuard | Cloudflare domain security management | UI only (needs Cloudflare API) | -| 6 | Git-Private-Farm | Farm | Repo inventory (~265 repos), health scores, Dependabot queue | UI only (needs local JSON read) | -| 7 | Palimpsest Plaza | Plaza | PMPL licensing adoption, compliance audits, signatures | UI only (needs filesystem scan) | -| 8 | Reposystem | Reposystem | RSR compliance scores, template validation, language policy | UI only (needs filesystem scan) | -| 9 | Aerie | Aerie | Network diagnostics, speed tests, BGP forensics, proof envelopes | UI only (needs V-lang API) | -| 10 | Interfaces | Interfaces | Idris2 ABI inventory, Zig FFI build status, binding coverage | UI only (needs filesystem scan) | -| 11 | Playgrounds | Playgrounds | Multi-language code sandbox, NQC database console, tutorials | UI only (needs NQC proxy) | -| 12 | Hypatia | Hypatia | Neurosymbolic CI/CD: 5 neural nets, 298 repos, safety triangle | UI only (needs Elixir API) | -| 13 | Fleet (Gitbot-Fleet) | Fleet | 6-bot orchestration dashboard, findings, dispatch queue | UI only (needs Axum API) | -| 14 | Minter (Panel Minter) | Minter | Create new panel modules with accessibility by default | UI only (Rust backend exists) | - -### Infrastructure Layers (4) - -| Layer | Module | What It Does | Status | -|-------|--------|-------------|--------| -| Panel Switcher | PanelSwitcher + PanelRegistry | Unified navigation bar (replaces ad-hoc toggles) | Working | -| Provisioner | Provisioner + ProvisionerEngine | Portfolio bundles, per-panel config, isolation tiers (Native/StandardPod/HardenedPod) | UI complete, not wired to backends | -| Code Provenance Map | Provenance + ProvenanceEngine | Qubes-style trust surface (git blame to semantic colours), accessibility palettes, hostile UX | UI complete, needs git blame integration | -| Filesystem Watcher | Watcher + WatcherCmd | notify/inotify event feed into TEA loop, all panels subscribe | Rust backend complete, needs frontend event hookup | - -### Cognitive Governance (Always Present) - -These subsystems are embedded across the entire interface and are not standalone panels. They represent the neurosymbolic intelligence layer that makes PanLL more than a dashboard: - -- **Vexometer** -- friction monitoring (cancellations, corrections, dwell time) -- **Anti-Crash Gate** -- circuit breaker between Panel-N and Panel-W -- **Orbital Drift Aura** -- ambient visual indicator of system stability -- **Feedback-O-Tron** -- feedback submission (expanding to opinion mining) -- **Information Humidity** -- UI density adapts to cognitive load (High/Medium/Low) -- **Dark Start** -- intentional entry (architecture manifold on launch) - ---- - -## Roadmap Sprints - -### Sprint 1 -- "Make It Breathe" (Polish + First Run) - -Priority scoring: **C** = Complexity (1--5), **E** = Effort (sessions), **V** = Value (1--5), **Score** = V / (C x E). Higher score means better return on investment. - -| # | Item | C | E | V | Score | Description | -|---|------|---|---|---|-------|-------------| -| 1 | Dark Start first-run polish | 1 | 1 | 4 | 4.00 | Auto-detect installed backends, show connection status on launch, polish entry animation | -| 2 | Tauri event wiring | 2 | 2 | 5 | 1.25 | Connect Watcher events to panel refresh, panel switcher to backend lifecycle. Makes the app feel alive. | -| 3 | Accessibility pass | 2 | 2 | 4 | 1.00 | Full keyboard nav, screen reader testing, all 4 colour palettes verified. Essential before any public showing. | - -### Sprint 2 -- "Make It Real" (Backend Connections) - -| # | Item | C | E | V | Score | Description | -|---|------|---|---|---|-------|-------------| -| 4 | Rust backend: Farm | 2 | 1 | 4 | 2.00 | Read ~/.git-private-farm/farm-manifest.json. Simplest backend -- local JSON, no HTTP. | -| 5 | Rust backend: Fleet | 2 | 2 | 4 | 1.00 | reqwest to existing gitbot-fleet Axum dashboard API (:8080). Has /api/health, /api/status, /api/findings. | -| 6 | Provenance Map git-blame integration | 3 | 2 | 4 | 0.67 | Wire ProvenanceCmd to actual git blame output parsing. Makes trust surface real, not placeholder. | -| 7 | Cross-panel bus (PanelBus) | 2 | 2 | 3 | 0.75 | Hypatia findings to Fleet dispatch, Farm inventory to Reposystem scanning. Panels communicate. | -| 8 | Feedback-O-Tron opinion mining | 2 | 2 | 4 | 1.00 | Aggregate feedback signals across panels, sentiment tracking, friction heatmap. Feeds Vexometer. | - -### Sprint 3 -- "Make It Complete" (Remaining Backends) - -| # | Item | C | E | V | Score | Description | -|---|------|---|---|---|-------|-------------| -| 9 | Rust backend: Hypatia | 3 | 3 | 5 | 0.56 | reqwest to Hypatia Elixir API. Most important panel -- 5 neural networks scanning 298 repos. | -| 10 | Rust backend: Aerie | 3 | 2 | 3 | 0.50 | reqwest to V-lang API gateway (GraphQL:4000, REST:4000). | -| 11 | NQC console in Playgrounds | 2 | 2 | 3 | 0.75 | Wire existing NQC web UI proxy (:4000) into Playgrounds panel. | -| 12 | Rust backend: Reposystem + Plaza | 2 | 2 | 3 | 0.75 | Filesystem scanning for .machine_readable/, editorconfig, Justfile, TOPOLOGY.md, LICENSE. | -| 13 | Provisioner install flow | 3 | 3 | 4 | 0.44 | Wire to Stapeln pod creation, binary downloads, config persistence. | - -### Sprint 4 -- "Make It Extensible" (Community Features) - -| # | Item | C | E | V | Score | Description | -|---|------|---|---|---|-------|-------------| -| 14 | Odds & Sods (Package Manager) | 3 | 3 | 3 | 0.33 | New panel #15. Unified Cargo/Gleam/Mix/Deno/asdf/Idris2/Zig view. The "stuff that doesn't fit" tracker. | -| 15 | Stapeln pod integration | 4 | 4 | 3 | 0.19 | Real container lifecycle for panel isolation tiers. Three defaults: no pod, Alpine+Podman, Stapeln+Chainguard. | -| 16 | Wharf (WordPress) | 3 | 3 | 4 | 0.44 | WP Wharf panel -- Nickel configs, Mooring Protocol, php-aegis. 43% of web runs WordPress. | -| 17 | TypLL (Language Panel) | 4 | 5 | 3 | 0.15 | Core language development panel for Eclexia/AffineScript/Anvomidav/Ephapax. | -| 18 | Valence Shell integration | 3 | 3 | 2 | 0.22 | CLI tool switchable with bash. Interesting for power users, not critical for Alpha. | -| 19 | Micropatching + reversibility | 4 | 4 | 2 | 0.13 | Undo system for config changes. Important eventually, deferred. | - -### Sprint 5 — "Code MRI" (Mutual Recognition & Integrity) - -Code MRI is the development transparency system — Turnitin for code, but collaborative not adversarial. See DD-016 in DESIGN-DECISIONS.md. - -| # | Item | C | E | V | Score | Description | -|---|------|---|---|---|-------|-------------| -| 20 | VoiceTag (Layer 0) | 3 | 2 | 5 | 0.83 | Voice/keyboard annotation on code regions. Numbered tags, attribution, simple grammar. Entry point to the full MRI system. (Also in Sprint 2 as it extends Provenance.) | -| 21 | Blake3 Provenance Chain (Layer 1) | 3 | 3 | 4 | 0.44 | Tamper-resistant attribution hashes per code region. Import/export carry provenance. | -| 22 | VeriSimDB Development Timeline (Layer 2) | 4 | 4 | 5 | 0.31 | Development-as-time-series. Timeline scrubber, snapshot rollback, "end credits" documentary view. Dogfoods VeriSimDB. | -| 23 | Pattern Diagnostics & Gamification (Layer 3) | 3 | 3 | 4 | 0.44 | AI bullshit detector, efficiency patterns, victory conditions, badges. Admin enforcement for education. | -| 24 | Attribution-to-Licensing Link (Layer 4) | 2 | 2 | 3 | 0.75 | Auto-generate PMPL/MPL attribution from provenance chains. Machine-verifiable license compliance. | -| 25 | Metrics & Learning Panel | 3 | 3 | 4 | 0.44 | ML-driven pattern identification from Code MRI data. Recommends support for struggling developers, suggests task reassignment based on strengths. Connects to Hypatia's neural networks for higher-order pattern detection. | - -### Future / Community Contributed - -- Game panels: Godot, Unity, Unreal Engine, IDApTIK level architect -- IDE integration: VSCode/VSCodium extension (export core as extension) -- Minecraft modding panel -- Statistease analytics panel -- eNSAID v1.0 specification publication - ---- - -## Version Milestones - -| Version | Target | Focus | Gate | -|---------|--------|-------|------| -| v0.2.0-alpha | Q1 2026 | Sprint 1 complete, Dark Start polished, accessibility verified | All keyboard nav works, screen reader tested | -| v0.3.0-alpha | Q2 2026 | Sprint 2 complete, Farm + Fleet backends live, Provenance real | At least 2 backends return real data | -| v0.4.0-beta | Q3 2026 | Sprint 3 complete, Hypatia + Aerie live, NQC in Playgrounds | 5+ backends connected, cross-panel bus working | -| v0.5.0-beta | Q4 2026 | Sprint 4 started, Odds & Sods, Wharf, Stapeln pods | Community contribution path documented | -| v0.6.0-beta | Q1 2027 | Sprint 5: Code MRI Layers 0-1 (VoiceTag + Blake3 chain) | Voice annotation working, provenance tamper-resistant | -| v0.7.0-beta | Q2 2027 | Sprint 5: Code MRI Layers 2-4 (Timeline + Diagnostics + Licensing) | VeriSimDB timeline scrubber, admin enforcement mode | -| v1.0.0 | H2 2027 | eNSAID spec v1.0, all core panels CRG Grade B+, stable API | Field-proven with real users | - ---- - -## Component Readiness Grades (CRG) - -CRG is PanLL's internal quality rubric. Every panel, infrastructure layer, and cognitive governance subsystem receives a letter grade that reflects its maturity. The grading system is deliberately strict: most software would land at D or E on first release. - -| Grade | Meaning | Criteria | -|-------|---------|----------| -| X | Untested | No tests, no usage, unknown state | -| F | Harmful | Known bugs, security issues, actively dangerous | -| E | Minimal | Compiles, basic structure, stubs | -| D | Alpha | Feature-complete UI, compiles clean, not connected to real backends | -| C | Beta | Connected to real backends, dogfooded by author | -| B | RC | Broadly validated, community tested, documented | -| A | Stable | Field-proven, formally verified where applicable, production-ready | - -**Current state:** All 14 panels are CRG Grade **D**. The four infrastructure layers range from D to E depending on backend wiring. Cognitive governance subsystems are Grade D (logic present, no real-world signal yet). - -**Target for public showing:** At least Farm + Fleet at Grade **C** (real data flowing, author-dogfooded). - ---- - -## Cross-Panel Communication Map - -The following data flows describe planned inter-panel communication via the PanelBus (Sprint 2, item 7). Each arrow represents a typed message channel. No panel directly imports another; all communication is mediated by the bus. - -| Source | Destination | Data Flow | Purpose | -|--------|-------------|-----------|---------| -| Hypatia | Fleet | Scan findings with confidence | Fleet dispatch queue receives prioritised work items | -| Farm | Reposystem | Repo inventory | Compliance scanning targets derived from known repos | -| Farm | Hypatia | Repo list | Scanning targets for neurosymbolic CI/CD | -| Reposystem | Interfaces | Language bridges | Interface inventory updated when language map changes | -| Databases | Playgrounds | Module configs | Playground gallery populated from database profiles | -| Hypatia | Panel-N (core) | Neural confidence | Main reasoning display reflects CI/CD scan confidence | -| Watcher | All panels | Filesystem events | Targeted refresh when monitored files change on disk | -| Feedback-O-Tron | Vexometer | Sentiment signals | Friction index updated from aggregated user feedback | -| Provenance | Anti-Crash Gate | Trust levels | Validation thresholds adjusted based on code provenance | -| Provisioner | All panels | Isolation tier | Startup mode selection (native vs. StandardPod vs. HardenedPod) | - ---- - -*This roadmap is maintained as a living document. Update as sprints complete.* diff --git a/docs/archive/TAURI-COMMANDS.adoc b/docs/archive/TAURI-COMMANDS.adoc new file mode 100644 index 00000000..a442c589 --- /dev/null +++ b/docs/archive/TAURI-COMMANDS.adoc @@ -0,0 +1,731 @@ +== Tauri Commands + +All commands registered in `+src-tauri/src/main.rs+` via +`+tauri::generate_handler![]+`. Frontend code calls these with +`+invoke("command_name", { params })+` from `+@tauri-apps/api+`. + +=== Top-Level Commands (main.rs) + +Commands defined directly in `+main.rs+`, not in a sub-module. + +[width="99%",cols="26%,28%,23%,23%",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+health_check+` |`+endpoint: String+` |`+Result+` +|Panel Switcher (connection dots) + +|`+validate_inference+` |inference payload |`+Result+` +|Anti-Crash Gate + +|`+record_vexation_event+` |event type |`+Result<(), String>+` +|Vexometer + +|`+get_vexation_index+` |(none) |`+Result+` |Vexometer + +|`+submit_feedback+` |feedback payload |`+Result+` +|Feedback-O-Tron + +|`+import_panic_attacker_report+` |file path |`+Result+` +|panic-attack panel + +|`+import_latest_panic_attacker_report+` |(none) +|`+Result+` |panic-attack panel + +|`+get_panic_attacker_capability+` |(none) |`+Result+` +|panic-attack panel + +|`+run_panic_attack_ambush+` |`+AmbushOptions+` +|`+Result+` |panic-attack panel + +|`+protocol_squisher_check+` |(none) |`+Result+` +|Protocol-Squisher + +|`+protocol_squisher_analyze+` |schema input |`+Result+` +|Protocol-Squisher + +|`+protocol_squisher_compare+` |two schemas |`+Result+` +|Protocol-Squisher + +|`+mylang_check+` |(none) |`+Result+` |My-Lang + +|`+mylang_compile+` |source code |`+Result+` |My-Lang + +|`+mylang_repl+` |expression |`+Result+` |My-Lang + +|`+mylang_lsp_connect+` |server config |`+Result+` +|My-Lang + +|`+mylang_lsp_diagnostics+` |file path |`+Result+` +|My-Lang +|=== + +==== VeriSimDB Commands (main.rs) + +[width="99%",cols="26%,28%,23%,23%",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+verisim_health+` |(none) |`+Result+` |Databases panel + +|`+verisim_query+` |VCL query string |`+Result+` +|Databases, Panel-W + +|`+verisim_list_hexads+` |(none) |`+Result+` |Databases +panel + +|`+verisim_get_drift+` |hexad ID |`+Result+` |Databases +panel + +|`+verisim_normalise+` |entity data |`+Result+` +|Databases panel + +|`+verisim_get_entity+` |entity ID |`+Result+` |Databases +panel + +|`+verisim_telemetry+` |(none) |`+Result+` |Databases +panel + +|`+verisim_orch_status+` |(none) |`+Result+` |Databases +panel +|=== + +==== ECHIDNA Commands (main.rs) + +[width="99%",cols="26%,28%,23%,23%",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+echidna_health+` |(none) |`+Result+` |Panel-N + +|`+echidna_list_provers+` |(none) |`+Result+` |Panel-N + +|`+echidna_prove+` |proposition |`+Result+` |Panel-N + +|`+echidna_verify+` |proof |`+Result+` |Panel-N + +|`+echidna_search_theorems+` |query |`+Result+` |Panel-N + +|`+echidna_create_session+` |session params |`+Result+` +|Panel-N + +|`+echidna_get_session+` |session ID |`+Result+` |Panel-N + +|`+echidna_apply_tactic+` |tactic + session |`+Result+` +|Panel-N + +|`+echidna_suggest_tactics+` |goal state |`+Result+` +|Panel-N +|=== + +=== cloudguard (14 commands) + +[width="99%",cols="26%,28%,23%,23%",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+cloudguard_verify_token+` |API token |`+Result+` +|CloudGuard + +|`+cloudguard_list_zones+` |(none) |`+Result+` +|CloudGuard + +|`+cloudguard_get_zone+` |zone ID |`+Result+` |CloudGuard + +|`+cloudguard_get_settings+` |zone ID |`+Result+` +|CloudGuard + +|`+cloudguard_update_setting+` |zone, key, value +|`+Result+` |CloudGuard + +|`+cloudguard_update_settings_batch+` |zone, settings +|`+Result+` |CloudGuard + +|`+cloudguard_list_dns_records+` |zone ID |`+Result+` +|CloudGuard + +|`+cloudguard_create_dns_record+` |zone, record +|`+Result+` |CloudGuard + +|`+cloudguard_update_dns_record+` |zone, record ID, data +|`+Result+` |CloudGuard + +|`+cloudguard_delete_dns_record+` |zone, record ID +|`+Result+` |CloudGuard + +|`+cloudguard_get_dnssec+` |zone ID |`+Result+` +|CloudGuard + +|`+cloudguard_enable_dnssec+` |zone ID |`+Result+` +|CloudGuard + +|`+cloudguard_harden_zone+` |zone ID |`+Result+` +|CloudGuard + +|`+cloudguard_download_config+` |zone ID |`+Result+` +|CloudGuard +|=== + +=== farm (3 commands) + +[cols=",,,",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+farm_list_repos+` |(none) |`+Result+` |Farm +|`+farm_get_repo+` |repo name |`+Result+` |Farm +|`+farm_get_stats+` |(none) |`+Result+` |Farm +|=== + +=== vm_inspector (7 commands) + +[width="99%",cols="26%,28%,23%,23%",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+vm_inspector_read_state+` |(none) |`+Result+` |VM +Inspector + +|`+vm_inspector_step_forward+` |(none) |`+Result+` |VM +Inspector + +|`+vm_inspector_step_backward+` |(none) |`+Result+` |VM +Inspector + +|`+vm_inspector_run+` |(none) |`+Result+` |VM Inspector + +|`+vm_inspector_load_program+` |bytecode |`+Result+` |VM +Inspector + +|`+vm_inspector_export_snapshot+` |(none) |`+Result+` |VM +Inspector + +|`+vm_inspector_read_file+` |file path |`+Result+` |VM +Inspector +|=== + +=== plaza (3 commands) + +[width="99%",cols="26%,28%,23%,23%",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+plaza_scan_repo+` |repo path |`+Result+` |Palimpsest +Plaza + +|`+plaza_adoption_stats+` |(none) |`+Result+` |Palimpsest +Plaza + +|`+plaza_check_compatibility+` |license ID |`+Result+` +|Palimpsest Plaza +|=== + +=== minter (2 commands) + +[width="99%",cols="26%,28%,23%,23%",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+minter_validate_name+` |panel name |`+Result+` |Minter +|`+minter_mint_panel+` |panel config |`+Result+` |Minter +|=== + +=== voicetag (4 commands) + +[cols=",,,",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+voicetag_load+` |file path |`+Result+` |Code MRI +|`+voicetag_save+` |file path, tags |`+Result<(), String>+` |Code MRI +|`+voicetag_delete+` |file path |`+Result<(), String>+` |Code MRI +|`+voicetag_scan+` |directory |`+Result+` |Code MRI +|=== + +=== watcher (5 commands) + +[width="99%",cols="26%,28%,23%,23%",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+watcher_start+` |(none) |`+Result<(), String>+` |Filesystem Watcher + +|`+watcher_stop+` |(none) |`+Result<(), String>+` |Filesystem Watcher + +|`+watcher_add_path+` |path |`+Result<(), String>+` |Filesystem Watcher + +|`+watcher_remove_path+` |path |`+Result<(), String>+` |Filesystem +Watcher + +|`+watcher_status+` |(none) |`+Result+` |Filesystem +Watcher +|=== + +=== ai (8 commands) + +[width="99%",cols="26%,28%,23%,23%",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+ai_send_message+` |message, provider |`+Result+` |AI +panel + +|`+ai_check_provider+` |provider name |`+Result+` |AI +panel + +|`+ai_set_model+` |provider, model |`+Result<(), String>+` |AI panel + +|`+ai_set_priority+` |provider list |`+Result<(), String>+` |AI panel + +|`+ai_toggle_provider+` |provider, enabled |`+Result<(), String>+` |AI +panel + +|`+ai_clear_history+` |(none) |`+Result<(), String>+` |AI panel + +|`+ai_build_context+` |panel state |`+Result+` |AI panel + +|`+ai_get_state+` |(none) |`+Result+` |AI panel +|=== + +=== repoloader (4 commands) + +[width="99%",cols="26%,28%,23%,23%",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+repoloader_scan+` |repo path |`+Result+` |Repo Loader + +|`+repoloader_save_panels+` |repo, panel list |`+Result<(), String>+` +|Repo Loader + +|`+repoloader_list_recent+` |(none) |`+Result+` |Repo +Loader + +|`+repoloader_search_farm+` |query |`+Result+` |Repo +Loader +|=== + +=== workspace (7 commands) + +[width="99%",cols="26%,28%,23%,23%",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+save_arrangement+` |arrangement data |`+Result<(), String>+` +|Workspace + +|`+load_arrangements+` |(none) |`+Result+` |Workspace + +|`+delete_arrangement+` |arrangement ID |`+Result<(), String>+` +|Workspace + +|`+save_session+` |session data |`+Result<(), String>+` |Workspace + +|`+load_sessions+` |(none) |`+Result+` |Workspace + +|`+delete_session+` |session ID |`+Result<(), String>+` |Workspace + +|`+get_system_info+` |(none) |`+Result+` |Workspace +|=== + +=== capture (5 commands) + +[width="99%",cols="26%,28%,23%,23%",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+save_screenshot+` |panel ID, data |`+Result+` +|Capture + +|`+print_panel+` |panel ID |`+Result+` |Capture + +|`+save_demo+` |demo data |`+Result<(), String>+` |Capture + +|`+load_demos+` |(none) |`+Result+` |Capture + +|`+delete_demo+` |demo ID |`+Result<(), String>+` |Capture +|=== + +=== security (5 commands) + +[cols=",,,",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+redact_text+` |text, patterns |`+Result+` |Security +|`+vault_store+` |key, value |`+Result<(), String>+` |Security +|`+vault_retrieve+` |key |`+Result+` |Security +|`+vault_list+` |(none) |`+Result+` |Security +|`+load_trustfile+` |path |`+Result+` |Security +|=== + +=== overlay (21 commands) + +[width="99%",cols="26%,28%,23%,23%",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+overlay_status+` |(none) |`+Result+` |Aerie + +|`+overlay_health+` |(none) |`+Result+` |Aerie + +|`+overlay_tor_connect+` |config |`+Result+` |Aerie + +|`+overlay_tor_disconnect+` |(none) |`+Result<(), String>+` |Aerie + +|`+overlay_tor_status+` |(none) |`+Result+` |Aerie + +|`+overlay_tor_create_hidden_service+` |service config +|`+Result+` |Aerie + +|`+overlay_tor_destroy_hidden_service+` |service ID +|`+Result<(), String>+` |Aerie + +|`+overlay_tor_list_circuits+` |(none) |`+Result+` |Aerie + +|`+overlay_tor_get_circuit+` |circuit ID |`+Result+` +|Aerie + +|`+overlay_tor_resolve+` |hostname |`+Result+` |Aerie + +|`+overlay_ipfs_connect+` |config |`+Result+` |Aerie + +|`+overlay_ipfs_disconnect+` |(none) |`+Result<(), String>+` |Aerie + +|`+overlay_ipfs_status+` |(none) |`+Result+` |Aerie + +|`+overlay_ipfs_add+` |data |`+Result+` |Aerie + +|`+overlay_ipfs_cat+` |CID |`+Result+` |Aerie + +|`+overlay_ipfs_pin+` |CID |`+Result<(), String>+` |Aerie + +|`+overlay_ipfs_unpin+` |CID |`+Result<(), String>+` |Aerie + +|`+overlay_ipfs_dag_get+` |CID |`+Result+` |Aerie + +|`+overlay_eth_connect+` |config |`+Result+` |Aerie + +|`+overlay_eth_disconnect+` |(none) |`+Result<(), String>+` |Aerie + +|`+overlay_eth_status+` |(none) |`+Result+` |Aerie + +|`+overlay_eth_timestamp_proof+` |data hash |`+Result+` +|Aerie + +|`+overlay_eth_verify_timestamp+` |proof |`+Result+` +|Aerie +|=== + +=== boj (8 commands) + +[width="99%",cols="26%,28%,23%,23%",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+boj_health+` |(none) |`+Result+` |BoJ +|`+boj_list_cartridges+` |(none) |`+Result+` |BoJ +|`+boj_get_cartridge+` |cartridge ID |`+Result+` |BoJ +|`+boj_load_cartridge+` |cartridge ID |`+Result+` |BoJ +|`+boj_unload_cartridge+` |cartridge ID |`+Result+` |BoJ +|`+boj_topology+` |(none) |`+Result+` |BoJ +|`+boj_invoke+` |cartridge, method, args |`+Result+` |BoJ +|`+boj_umoja_status+` |(none) |`+Result+` |BoJ +|=== + +=== typell (7 commands) + +[width="99%",cols="26%,28%,23%,23%",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+typell_health+` |(none) |`+Result+` |TypeLL +|`+typell_check+` |type expression |`+Result+` |TypeLL +|`+typell_infer+` |expression |`+Result+` |TypeLL +|`+typell_refine+` |type + refinement |`+Result+` |TypeLL +|`+typell_compute+` |computation |`+Result+` |TypeLL +|`+typell_list_signatures+` |(none) |`+Result+` |TypeLL +|`+typell_universes+` |(none) |`+Result+` |TypeLL +|=== + +=== clade_scanner (1 command) + +[width="99%",cols="26%,28%,23%,23%",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+scan_clade_files+` |(none) |`+Result+` |Clade Browser +|=== + +=== governance (3 commands) + +[width="99%",cols="26%,28%,23%,23%",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+governance_nesy_query+` |query |`+Result+` |Cognitive +Governance + +|`+governance_nesy_validate+` |validation input +|`+Result+` |Cognitive Governance + +|`+governance_nesy_probe+` |probe target |`+Result+` +|Cognitive Governance +|=== + +=== coprocessor (8 commands) + +[width="99%",cols="26%,28%,23%,23%",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+query_compute_engine+` |engine query |`+Result+` +|Coprocessors + +|`+discover_compute_devices+` |(none) |`+Result+` +|Coprocessors + +|`+coprocessor_dispatch_local+` |task |`+Result+` +|Coprocessors + +|`+coprocessor_check_ffi+` |FFI target |`+Result+` +|Coprocessors + +|`+coprocessor_benchmark+` |benchmark config |`+Result+` +|Coprocessors + +|`+coprocessor_load_ffi+` |FFI module |`+Result+` +|Coprocessors + +|`+coprocessor_local_resources+` |(none) |`+Result+` +|Coprocessors + +|`+coprocessor_smart_dispatch+` |task + routing +|`+Result+` |Coprocessors +|=== + +=== game_preview (8 commands) + +[width="99%",cols="26%,28%,23%,23%",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+game_preview_check_server+` |(none) |`+Result+` |Game +Preview + +|`+game_preview_control+` |control action |`+Result+` +|Game Preview + +|`+game_preview_record_start+` |(none) |`+Result<(), String>+` |Game +Preview + +|`+game_preview_record_stop+` |(none) |`+Result+` |Game +Preview + +|`+game_preview_screenshot+` |(none) |`+Result+` |Game +Preview + +|`+game_preview_stats+` |(none) |`+Result+` |Game Preview + +|`+game_preview_clips_list+` |(none) |`+Result+` |Game +Preview + +|`+game_preview_clip_delete+` |clip ID |`+Result<(), String>+` |Game +Preview +|=== + +=== network_topology (4 commands) + +[width="99%",cols="26%,28%,23%,23%",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+read_network_topology+` |(none) |`+Result+` |Network +Topology + +|`+read_dns_table+` |(none) |`+Result+` |Network Topology + +|`+read_packet_flow+` |(none) |`+Result+` |Network +Topology + +|`+export_topology_svg+` |(none) |`+Result+` |Network +Topology +|=== + +=== level_architect (5 commands) + +[width="99%",cols="26%,28%,23%,23%",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+load_level+` |level path |`+Result+` |Level Architect + +|`+save_level+` |level data |`+Result<(), String>+` |Level Architect + +|`+export_level_config+` |level ID |`+Result+` |Level +Architect + +|`+browse_level_assets+` |asset type |`+Result+` |Level +Architect + +|`+validate_level+` |level data |`+Result+` |Level +Architect +|=== + +=== valence_shell (12 commands) + +[width="99%",cols="26%,28%,23%,23%",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+valence_shell_check+` |(none) |`+Result+` |Valence +Shell + +|`+valence_shell_spawn+` |shell config |`+Result+` +|Valence Shell + +|`+valence_shell_input+` |session, input |`+Result<(), String>+` +|Valence Shell + +|`+valence_shell_record_start+` |session |`+Result<(), String>+` +|Valence Shell + +|`+valence_shell_record_stop+` |session |`+Result+` +|Valence Shell + +|`+valence_shell_recordings_list+` |(none) |`+Result+` +|Valence Shell + +|`+valence_shell_recording_delete+` |recording ID +|`+Result<(), String>+` |Valence Shell + +|`+valence_shell_checkpoint_create+` |session |`+Result+` +|Valence Shell + +|`+valence_shell_checkpoint_restore+` |checkpoint ID +|`+Result+` |Valence Shell + +|`+valence_shell_checkpoints_list+` |session |`+Result+` +|Valence Shell + +|`+valence_shell_screenshot+` |session |`+Result+` +|Valence Shell + +|`+valence_shell_recording_export+` |recording, format +|`+Result+` |Valence Shell +|=== + +=== multiplayer_monitor (6 commands) + +[width="99%",cols="26%,28%,23%,23%",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+multiplayer_connect+` |server URL |`+Result+` +|Multiplayer Monitor + +|`+multiplayer_disconnect+` |(none) |`+Result<(), String>+` |Multiplayer +Monitor + +|`+multiplayer_read_state+` |(none) |`+Result+` +|Multiplayer Monitor + +|`+multiplayer_read_diffs+` |(none) |`+Result+` +|Multiplayer Monitor + +|`+multiplayer_read_ets+` |(none) |`+Result+` +|Multiplayer Monitor + +|`+multiplayer_reconnection_test+` |(none) |`+Result+` +|Multiplayer Monitor +|=== + +=== dlc_workshop (8 commands) + +[width="99%",cols="26%,28%,23%,23%",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+dlc_load_puzzles+` |pack path |`+Result+` |DLC +Workshop + +|`+dlc_save_puzzle+` |puzzle data |`+Result<(), String>+` |DLC Workshop + +|`+dlc_run_test+` |puzzle ID |`+Result+` |DLC Workshop + +|`+dlc_run_all_tests+` |pack path |`+Result+` |DLC +Workshop + +|`+dlc_browse_assets+` |asset type |`+Result+` |DLC +Workshop + +|`+dlc_package+` |pack config |`+Result+` |DLC Workshop + +|`+dlc_import_puzzle+` |file path |`+Result+` |DLC +Workshop + +|`+dlc_export_puzzle+` |puzzle ID |`+Result+` |DLC +Workshop +|=== + +=== release_manager (5 commands) + +[width="99%",cols="26%,28%,23%,23%",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+release_generate_changelog+` |version range +|`+Result+` |Release Manager + +|`+release_build_artifacts+` |build config |`+Result+` +|Release Manager + +|`+release_publish+` |release config |`+Result+` |Release +Manager + +|`+release_read_history+` |(none) |`+Result+` |Release +Manager + +|`+release_bump_version+` |bump type |`+Result+` +|Release Manager +|=== + +=== umoja (5 commands) + +[width="99%",cols="26%,28%,23%,23%",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+umoja_add_peer+` |peer address |`+Result+` |BoJ +(federation) + +|`+umoja_disconnect_peer+` |peer ID |`+Result<(), String>+` |BoJ +(federation) + +|`+umoja_trigger_gossip+` |(none) |`+Result+` |BoJ +(federation) + +|`+umoja_sync_catalogue+` |peer ID |`+Result+` |BoJ +(federation) + +|`+umoja_peer_metrics+` |(none) |`+Result+` |BoJ +(federation) +|=== + +=== observability (3 commands) + +[width="99%",cols="26%,28%,23%,23%",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+observe_export_sarif+` |scan results |`+Result+` +|Observability + +|`+observe_export_traces+` |trace config |`+Result+` +|Observability + +|`+observe_summary+` |(none) |`+Result+` |Observability +|=== + +=== a2ml (3 commands) + +[width="99%",cols="26%,28%,23%,23%",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+a2ml_load_manifest+` |file path |`+Result+` |A2ML +integration + +|`+a2ml_validate+` |manifest data |`+Result+` |A2ML +integration + +|`+a2ml_list+` |directory |`+Result+` |A2ML integration +|=== + +=== k9 (3 commands) + +[width="99%",cols="26%,28%,23%,23%",options="header",] +|=== +|Command |Parameters |Returns |Used By +|`+k9_load_contractile+` |file path |`+Result+` |K9 +integration + +|`+k9_validate+` |contractile data |`+Result+` |K9 +integration + +|`+k9_apply_layout+` |layout config |`+Result+` |K9 +integration +|=== + +''''' + +*Total: 246 Tauri commands* across 26 modules + top-level. diff --git a/docs/archive/TAURI-COMMANDS.md b/docs/archive/TAURI-COMMANDS.md deleted file mode 100644 index a9c7b246..00000000 --- a/docs/archive/TAURI-COMMANDS.md +++ /dev/null @@ -1,388 +0,0 @@ - - - - -# Tauri Commands - -All commands registered in `src-tauri/src/main.rs` via `tauri::generate_handler![]`. -Frontend code calls these with `invoke("command_name", { params })` from -`@tauri-apps/api`. - -## Top-Level Commands (main.rs) - -Commands defined directly in `main.rs`, not in a sub-module. - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `health_check` | `endpoint: String` | `Result` | Panel Switcher (connection dots) | -| `validate_inference` | inference payload | `Result` | Anti-Crash Gate | -| `record_vexation_event` | event type | `Result<(), String>` | Vexometer | -| `get_vexation_index` | (none) | `Result` | Vexometer | -| `submit_feedback` | feedback payload | `Result` | Feedback-O-Tron | -| `import_panic_attacker_report` | file path | `Result` | panic-attack panel | -| `import_latest_panic_attacker_report` | (none) | `Result` | panic-attack panel | -| `get_panic_attacker_capability` | (none) | `Result` | panic-attack panel | -| `run_panic_attack_ambush` | `AmbushOptions` | `Result` | panic-attack panel | -| `protocol_squisher_check` | (none) | `Result` | Protocol-Squisher | -| `protocol_squisher_analyze` | schema input | `Result` | Protocol-Squisher | -| `protocol_squisher_compare` | two schemas | `Result` | Protocol-Squisher | -| `mylang_check` | (none) | `Result` | My-Lang | -| `mylang_compile` | source code | `Result` | My-Lang | -| `mylang_repl` | expression | `Result` | My-Lang | -| `mylang_lsp_connect` | server config | `Result` | My-Lang | -| `mylang_lsp_diagnostics` | file path | `Result` | My-Lang | - -### VeriSimDB Commands (main.rs) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `verisim_health` | (none) | `Result` | Databases panel | -| `verisim_query` | VCL query string | `Result` | Databases, Panel-W | -| `verisim_list_hexads` | (none) | `Result` | Databases panel | -| `verisim_get_drift` | hexad ID | `Result` | Databases panel | -| `verisim_normalise` | entity data | `Result` | Databases panel | -| `verisim_get_entity` | entity ID | `Result` | Databases panel | -| `verisim_telemetry` | (none) | `Result` | Databases panel | -| `verisim_orch_status` | (none) | `Result` | Databases panel | - -### ECHIDNA Commands (main.rs) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `echidna_health` | (none) | `Result` | Panel-N | -| `echidna_list_provers` | (none) | `Result` | Panel-N | -| `echidna_prove` | proposition | `Result` | Panel-N | -| `echidna_verify` | proof | `Result` | Panel-N | -| `echidna_search_theorems` | query | `Result` | Panel-N | -| `echidna_create_session` | session params | `Result` | Panel-N | -| `echidna_get_session` | session ID | `Result` | Panel-N | -| `echidna_apply_tactic` | tactic + session | `Result` | Panel-N | -| `echidna_suggest_tactics` | goal state | `Result` | Panel-N | - -## cloudguard (14 commands) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `cloudguard_verify_token` | API token | `Result` | CloudGuard | -| `cloudguard_list_zones` | (none) | `Result` | CloudGuard | -| `cloudguard_get_zone` | zone ID | `Result` | CloudGuard | -| `cloudguard_get_settings` | zone ID | `Result` | CloudGuard | -| `cloudguard_update_setting` | zone, key, value | `Result` | CloudGuard | -| `cloudguard_update_settings_batch` | zone, settings | `Result` | CloudGuard | -| `cloudguard_list_dns_records` | zone ID | `Result` | CloudGuard | -| `cloudguard_create_dns_record` | zone, record | `Result` | CloudGuard | -| `cloudguard_update_dns_record` | zone, record ID, data | `Result` | CloudGuard | -| `cloudguard_delete_dns_record` | zone, record ID | `Result` | CloudGuard | -| `cloudguard_get_dnssec` | zone ID | `Result` | CloudGuard | -| `cloudguard_enable_dnssec` | zone ID | `Result` | CloudGuard | -| `cloudguard_harden_zone` | zone ID | `Result` | CloudGuard | -| `cloudguard_download_config` | zone ID | `Result` | CloudGuard | - -## farm (3 commands) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `farm_list_repos` | (none) | `Result` | Farm | -| `farm_get_repo` | repo name | `Result` | Farm | -| `farm_get_stats` | (none) | `Result` | Farm | - -## vm_inspector (7 commands) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `vm_inspector_read_state` | (none) | `Result` | VM Inspector | -| `vm_inspector_step_forward` | (none) | `Result` | VM Inspector | -| `vm_inspector_step_backward` | (none) | `Result` | VM Inspector | -| `vm_inspector_run` | (none) | `Result` | VM Inspector | -| `vm_inspector_load_program` | bytecode | `Result` | VM Inspector | -| `vm_inspector_export_snapshot` | (none) | `Result` | VM Inspector | -| `vm_inspector_read_file` | file path | `Result` | VM Inspector | - -## plaza (3 commands) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `plaza_scan_repo` | repo path | `Result` | Palimpsest Plaza | -| `plaza_adoption_stats` | (none) | `Result` | Palimpsest Plaza | -| `plaza_check_compatibility` | license ID | `Result` | Palimpsest Plaza | - -## minter (2 commands) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `minter_validate_name` | panel name | `Result` | Minter | -| `minter_mint_panel` | panel config | `Result` | Minter | - -## voicetag (4 commands) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `voicetag_load` | file path | `Result` | Code MRI | -| `voicetag_save` | file path, tags | `Result<(), String>` | Code MRI | -| `voicetag_delete` | file path | `Result<(), String>` | Code MRI | -| `voicetag_scan` | directory | `Result` | Code MRI | - -## watcher (5 commands) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `watcher_start` | (none) | `Result<(), String>` | Filesystem Watcher | -| `watcher_stop` | (none) | `Result<(), String>` | Filesystem Watcher | -| `watcher_add_path` | path | `Result<(), String>` | Filesystem Watcher | -| `watcher_remove_path` | path | `Result<(), String>` | Filesystem Watcher | -| `watcher_status` | (none) | `Result` | Filesystem Watcher | - -## ai (8 commands) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `ai_send_message` | message, provider | `Result` | AI panel | -| `ai_check_provider` | provider name | `Result` | AI panel | -| `ai_set_model` | provider, model | `Result<(), String>` | AI panel | -| `ai_set_priority` | provider list | `Result<(), String>` | AI panel | -| `ai_toggle_provider` | provider, enabled | `Result<(), String>` | AI panel | -| `ai_clear_history` | (none) | `Result<(), String>` | AI panel | -| `ai_build_context` | panel state | `Result` | AI panel | -| `ai_get_state` | (none) | `Result` | AI panel | - -## repoloader (4 commands) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `repoloader_scan` | repo path | `Result` | Repo Loader | -| `repoloader_save_panels` | repo, panel list | `Result<(), String>` | Repo Loader | -| `repoloader_list_recent` | (none) | `Result` | Repo Loader | -| `repoloader_search_farm` | query | `Result` | Repo Loader | - -## workspace (7 commands) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `save_arrangement` | arrangement data | `Result<(), String>` | Workspace | -| `load_arrangements` | (none) | `Result` | Workspace | -| `delete_arrangement` | arrangement ID | `Result<(), String>` | Workspace | -| `save_session` | session data | `Result<(), String>` | Workspace | -| `load_sessions` | (none) | `Result` | Workspace | -| `delete_session` | session ID | `Result<(), String>` | Workspace | -| `get_system_info` | (none) | `Result` | Workspace | - -## capture (5 commands) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `save_screenshot` | panel ID, data | `Result` | Capture | -| `print_panel` | panel ID | `Result` | Capture | -| `save_demo` | demo data | `Result<(), String>` | Capture | -| `load_demos` | (none) | `Result` | Capture | -| `delete_demo` | demo ID | `Result<(), String>` | Capture | - -## security (5 commands) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `redact_text` | text, patterns | `Result` | Security | -| `vault_store` | key, value | `Result<(), String>` | Security | -| `vault_retrieve` | key | `Result` | Security | -| `vault_list` | (none) | `Result` | Security | -| `load_trustfile` | path | `Result` | Security | - -## overlay (21 commands) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `overlay_status` | (none) | `Result` | Aerie | -| `overlay_health` | (none) | `Result` | Aerie | -| `overlay_tor_connect` | config | `Result` | Aerie | -| `overlay_tor_disconnect` | (none) | `Result<(), String>` | Aerie | -| `overlay_tor_status` | (none) | `Result` | Aerie | -| `overlay_tor_create_hidden_service` | service config | `Result` | Aerie | -| `overlay_tor_destroy_hidden_service` | service ID | `Result<(), String>` | Aerie | -| `overlay_tor_list_circuits` | (none) | `Result` | Aerie | -| `overlay_tor_get_circuit` | circuit ID | `Result` | Aerie | -| `overlay_tor_resolve` | hostname | `Result` | Aerie | -| `overlay_ipfs_connect` | config | `Result` | Aerie | -| `overlay_ipfs_disconnect` | (none) | `Result<(), String>` | Aerie | -| `overlay_ipfs_status` | (none) | `Result` | Aerie | -| `overlay_ipfs_add` | data | `Result` | Aerie | -| `overlay_ipfs_cat` | CID | `Result` | Aerie | -| `overlay_ipfs_pin` | CID | `Result<(), String>` | Aerie | -| `overlay_ipfs_unpin` | CID | `Result<(), String>` | Aerie | -| `overlay_ipfs_dag_get` | CID | `Result` | Aerie | -| `overlay_eth_connect` | config | `Result` | Aerie | -| `overlay_eth_disconnect` | (none) | `Result<(), String>` | Aerie | -| `overlay_eth_status` | (none) | `Result` | Aerie | -| `overlay_eth_timestamp_proof` | data hash | `Result` | Aerie | -| `overlay_eth_verify_timestamp` | proof | `Result` | Aerie | - -## boj (8 commands) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `boj_health` | (none) | `Result` | BoJ | -| `boj_list_cartridges` | (none) | `Result` | BoJ | -| `boj_get_cartridge` | cartridge ID | `Result` | BoJ | -| `boj_load_cartridge` | cartridge ID | `Result` | BoJ | -| `boj_unload_cartridge` | cartridge ID | `Result` | BoJ | -| `boj_topology` | (none) | `Result` | BoJ | -| `boj_invoke` | cartridge, method, args | `Result` | BoJ | -| `boj_umoja_status` | (none) | `Result` | BoJ | - -## typell (7 commands) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `typell_health` | (none) | `Result` | TypeLL | -| `typell_check` | type expression | `Result` | TypeLL | -| `typell_infer` | expression | `Result` | TypeLL | -| `typell_refine` | type + refinement | `Result` | TypeLL | -| `typell_compute` | computation | `Result` | TypeLL | -| `typell_list_signatures` | (none) | `Result` | TypeLL | -| `typell_universes` | (none) | `Result` | TypeLL | - -## clade_scanner (1 command) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `scan_clade_files` | (none) | `Result` | Clade Browser | - -## governance (3 commands) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `governance_nesy_query` | query | `Result` | Cognitive Governance | -| `governance_nesy_validate` | validation input | `Result` | Cognitive Governance | -| `governance_nesy_probe` | probe target | `Result` | Cognitive Governance | - -## coprocessor (8 commands) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `query_compute_engine` | engine query | `Result` | Coprocessors | -| `discover_compute_devices` | (none) | `Result` | Coprocessors | -| `coprocessor_dispatch_local` | task | `Result` | Coprocessors | -| `coprocessor_check_ffi` | FFI target | `Result` | Coprocessors | -| `coprocessor_benchmark` | benchmark config | `Result` | Coprocessors | -| `coprocessor_load_ffi` | FFI module | `Result` | Coprocessors | -| `coprocessor_local_resources` | (none) | `Result` | Coprocessors | -| `coprocessor_smart_dispatch` | task + routing | `Result` | Coprocessors | - -## game_preview (8 commands) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `game_preview_check_server` | (none) | `Result` | Game Preview | -| `game_preview_control` | control action | `Result` | Game Preview | -| `game_preview_record_start` | (none) | `Result<(), String>` | Game Preview | -| `game_preview_record_stop` | (none) | `Result` | Game Preview | -| `game_preview_screenshot` | (none) | `Result` | Game Preview | -| `game_preview_stats` | (none) | `Result` | Game Preview | -| `game_preview_clips_list` | (none) | `Result` | Game Preview | -| `game_preview_clip_delete` | clip ID | `Result<(), String>` | Game Preview | - -## network_topology (4 commands) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `read_network_topology` | (none) | `Result` | Network Topology | -| `read_dns_table` | (none) | `Result` | Network Topology | -| `read_packet_flow` | (none) | `Result` | Network Topology | -| `export_topology_svg` | (none) | `Result` | Network Topology | - -## level_architect (5 commands) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `load_level` | level path | `Result` | Level Architect | -| `save_level` | level data | `Result<(), String>` | Level Architect | -| `export_level_config` | level ID | `Result` | Level Architect | -| `browse_level_assets` | asset type | `Result` | Level Architect | -| `validate_level` | level data | `Result` | Level Architect | - -## valence_shell (12 commands) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `valence_shell_check` | (none) | `Result` | Valence Shell | -| `valence_shell_spawn` | shell config | `Result` | Valence Shell | -| `valence_shell_input` | session, input | `Result<(), String>` | Valence Shell | -| `valence_shell_record_start` | session | `Result<(), String>` | Valence Shell | -| `valence_shell_record_stop` | session | `Result` | Valence Shell | -| `valence_shell_recordings_list` | (none) | `Result` | Valence Shell | -| `valence_shell_recording_delete` | recording ID | `Result<(), String>` | Valence Shell | -| `valence_shell_checkpoint_create` | session | `Result` | Valence Shell | -| `valence_shell_checkpoint_restore` | checkpoint ID | `Result` | Valence Shell | -| `valence_shell_checkpoints_list` | session | `Result` | Valence Shell | -| `valence_shell_screenshot` | session | `Result` | Valence Shell | -| `valence_shell_recording_export` | recording, format | `Result` | Valence Shell | - -## multiplayer_monitor (6 commands) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `multiplayer_connect` | server URL | `Result` | Multiplayer Monitor | -| `multiplayer_disconnect` | (none) | `Result<(), String>` | Multiplayer Monitor | -| `multiplayer_read_state` | (none) | `Result` | Multiplayer Monitor | -| `multiplayer_read_diffs` | (none) | `Result` | Multiplayer Monitor | -| `multiplayer_read_ets` | (none) | `Result` | Multiplayer Monitor | -| `multiplayer_reconnection_test` | (none) | `Result` | Multiplayer Monitor | - -## dlc_workshop (8 commands) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `dlc_load_puzzles` | pack path | `Result` | DLC Workshop | -| `dlc_save_puzzle` | puzzle data | `Result<(), String>` | DLC Workshop | -| `dlc_run_test` | puzzle ID | `Result` | DLC Workshop | -| `dlc_run_all_tests` | pack path | `Result` | DLC Workshop | -| `dlc_browse_assets` | asset type | `Result` | DLC Workshop | -| `dlc_package` | pack config | `Result` | DLC Workshop | -| `dlc_import_puzzle` | file path | `Result` | DLC Workshop | -| `dlc_export_puzzle` | puzzle ID | `Result` | DLC Workshop | - -## release_manager (5 commands) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `release_generate_changelog` | version range | `Result` | Release Manager | -| `release_build_artifacts` | build config | `Result` | Release Manager | -| `release_publish` | release config | `Result` | Release Manager | -| `release_read_history` | (none) | `Result` | Release Manager | -| `release_bump_version` | bump type | `Result` | Release Manager | - -## umoja (5 commands) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `umoja_add_peer` | peer address | `Result` | BoJ (federation) | -| `umoja_disconnect_peer` | peer ID | `Result<(), String>` | BoJ (federation) | -| `umoja_trigger_gossip` | (none) | `Result` | BoJ (federation) | -| `umoja_sync_catalogue` | peer ID | `Result` | BoJ (federation) | -| `umoja_peer_metrics` | (none) | `Result` | BoJ (federation) | - -## observability (3 commands) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `observe_export_sarif` | scan results | `Result` | Observability | -| `observe_export_traces` | trace config | `Result` | Observability | -| `observe_summary` | (none) | `Result` | Observability | - -## a2ml (3 commands) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `a2ml_load_manifest` | file path | `Result` | A2ML integration | -| `a2ml_validate` | manifest data | `Result` | A2ML integration | -| `a2ml_list` | directory | `Result` | A2ML integration | - -## k9 (3 commands) - -| Command | Parameters | Returns | Used By | -|---------|-----------|---------|---------| -| `k9_load_contractile` | file path | `Result` | K9 integration | -| `k9_validate` | contractile data | `Result` | K9 integration | -| `k9_apply_layout` | layout config | `Result` | K9 integration | - ---- - -**Total: 246 Tauri commands** across 26 modules + top-level. diff --git a/docs/decisions/DESIGN-DECISIONS.adoc b/docs/decisions/DESIGN-DECISIONS.adoc new file mode 100644 index 00000000..d650bad6 --- /dev/null +++ b/docs/decisions/DESIGN-DECISIONS.adoc @@ -0,0 +1,585 @@ +== PanLL Design Decisions + +*Last updated: 2026-03-02* *Living document — updated as decisions are +made or revised* + +=== DD-001: eNSAID Is a Specification, PanLL Is an Implementation + +*Date:* 2026-02-27 *Status:* Accepted *Context:* Need to separate the +idea from the tool so others can build competing implementations. + +*Decision:* eNSAID (Environment for NeSy-Agentic Integrated Development) +is a specification. PanLL is the reference implementation. The spec +lives in its own repo with its own governance. PanLL claims +`+IMPLEMENTS eNSAID+` and that claim is verifiable. + +*Consequences:* - Contributors contribute to the eNSAID ecosystem, not +just PanLL - Every panel written works with any compliant eNSAID +environment - Pattern: HTTP → Apache/Nginx/Caddy. SQL → Postgres/MySQL. +LSP → every language server. - If someone builds a better eNSAID, the +idea survives + +*The V for Vendetta Principle:* You can kill PanLL. You cannot kill the +idea. Ideas are bulletproof. + +''''' + +=== DD-002: Binary Star Architecture (Human-Machine Co-Orbit) + +*Date:* 2026-01-15 *Status:* Accepted *Context:* Traditional IDEs treat +AI as subordinate tool. Need genuine co-working. + +*Decision:* Model Human and Machine as Binary Star system — two +gravitationally bound entities orbiting a shared Barycentre (the task). +Three panels: Panel-L (Symbolic/Human constraints), Panel-N +(Neural/Machine reasoning), Panel-W (World/Barycentre results). Neither +Human nor Machine is primary. + +*Consequences:* - Operator sees Machine reasoning in real-time (Panel-N) +- Machine constrained by symbolic rules visible to both (Panel-L) - +Shared output space validates mutual understanding (Panel-W) - Higher +cognitive load initially, offset by Vexometer monitoring + +''''' + +=== DD-003: The Elm Architecture (TEA) for State Management + +*Date:* 2026-01-20 *Status:* Accepted *Context:* Complex UI with 14 +panels, cognitive governance, orbital tracking needs deterministic +state. + +*Decision:* Model-Update-View with Commands and Subscriptions. Single +immutable model record. All state changes flow through typed messages. +Custom TEA implementation extended for PanLL’s needs. + +*Technical detail:* The main `+model+` type composes all domain slices +via `+include+` re-exports. Each panel has its own +Model/Engine/Cmd/Component files following a proven 8-file pattern. + +''''' + +=== DD-004: Panel Module Pattern (8 Files Per Panel) + +*Date:* 2026-03-01 *Status:* Accepted *Context:* Need a repeatable, +consistent pattern for adding panels. + +*Decision:* Every panel follows exactly 8 files: + +[cols=",,",options="header",] +|=== +|Layer |ReScript |Rust (if backend needed) +|Types |`+src/model/XModel.res+` |`+src-tauri/src/x/types.rs+` +|Engine |`+src/core/XEngine.res+` |— +|Commands |`+src/commands/XCmd.res+` |`+src-tauri/src/x/commands.rs+` +|Component |`+src/components/X.res+` |`+src-tauri/src/x/mod.rs+` +|=== + +Plus wiring into 5 global files: Msg.res, Model.res, Update.res, +View.res, main.rs + +*Consequences:* - Panel Minter can generate this structure automatically +- Every panel is structurally identical — contributors know where +everything is - Engine files are pure functions (no side effects) — +fully testable - Cmd files handle Tauri IPC — all effects isolated + +''''' + +=== DD-005: Three-Tier Panel Isolation (Native / Standard Pod / Hardened Pod) + +*Date:* 2026-03-02 *Status:* Accepted *Context:* Third-party panels +could be malicious or poorly written. Core panels should run fast. + +*Decision:* Three isolation tiers, selectable per panel via the +Provisioner: + +[width="100%",cols="15%,18%,20%,27%,20%",options="header",] +|=== +|Tier |Runtime |Security |Performance |Use Case +|*Native* |In-process (Tauri webview) |Full trust, hash-verified +|Fastest |Core 14 panels + +|*Standard Pod* |Alpine + Podman container |Process isolation, network +limited |Moderate overhead |Community panels, trusted + +|*Hardened Pod* |Stapeln + Chainguard image |Full Stapeln security +stack, minimal attack surface |Higher overhead |Untrusted/experimental +panels +|=== + +*Consequences:* - Core panels default to Native (no container overhead) +- Community panels default to StandardPod - Users can override in +Provisioner Configurator tab - Clean uninstall: delete the pod, +everything goes - Supply chain commitment: containers are not just +security, they’re reversibility + +''''' + +=== DD-006: Qubes-Style Code Provenance Map + +*Date:* 2026-03-02 *Status:* Accepted *Context:* Need to show who wrote +each line and how trustworthy it is. + +*Decision:* Always-visible ambient trust surface (not a toggle). Parses +git blame + Co-Authored-By headers. Fixed semantic colour meanings: + +[width="100%",cols="22%,22%,25%,31%",options="header",] +|=== +|Level |Colour |Meaning |Detection +|Verified |Green |Formally verified, proof-checked, no believe_me |Proof +markers in commit + +|Human-Reviewed |Blue |Human author or human commit after AI |No +co-author, or subsequent human commit + +|AI-Assisted |Amber |Co-authored, no subsequent human review +|Co-Authored-By present, no later human commit + +|Unreviewed AI |Red |Pure AI, no human in chain |AI author, no human +review + +|Unknown |Grey |Pre-git or no attribution |No blame data available +|=== + +*Key constraint:* Colours swap hues for accessibility palettes (4 +palettes: Standard, Deuteranopia, Protanopia, High Contrast) but NEVER +swap meanings. Green always means verified, regardless of the actual hue +displayed. + +*Hostile UX:* Unreviewed AI code gets pulsing red borders and increased +visual friction. Users CAN suppress this, but the suppression action is +itself visible ("`pulled the smoke alarm battery`"). + +''''' + +=== DD-007: Cognitive Governance Stack + +*Date:* 2026-01-25 *Status:* Accepted *Context:* Co-orbit increases +cognitive load. Need automated monitoring. + +*Decision:* Four interconnected governance systems: + +[arabic] +. *Anti-Crash Gate* — Circuit breaker between Panel-N output and Panel-W +workspace. Every neural token validated against Panel-L constraints +before reaching shared space. +. *Vexometer* — Friction monitor tracking cancellations, corrections, +dwell time. Index 0.0–1.0 triggers anti-inflammatory UI adjustments. +. *Information Humidity* — UI density adapts to stress. High humidity +(relaxed) = more detail. Low humidity (stressed) = essential info only. +. *Orbital Drift Aura* — Ambient visual (background colour shift) +indicating system stability. Visible without looking at any specific +panel. + +These feed each other: Feedback-O-Tron → Vexometer → Humidity → UI +adaptation. + +''''' + +=== DD-008: Accessibility as Core, Not Afterthought + +*Date:* 2026-02-27 *Status:* Accepted *Context:* Accessibility is +usually bolted on after launch. PanLL should be different. + +*Decision:* Accessibility is in the CORE infrastructure, not in +individual panels: - Panel Minter produces accessible panels by default +(harder to make inaccessible than accessible) - Every colour system +ships with 4 accessibility palettes - Every keyboard interaction works +without a mouse - Screen reader semantics (ARIA) in every component +template - Renamed broader concept to "`information/cognitive +ergonomics`" (accessibility is a subset) + +*The discipline covers:* - Perceptual load management (how much +information before overload) - Cognitive friction reduction (Vexometer +measures this) - Task-flow preservation (panels don’t interrupt flow) - +Multi-modal presentation (visual + auditory + haptic) - Expertise +scaffolding (novice → expert gradual complexity reveal) + +''''' + +=== DD-009: Trust & Blame Separation + +*Date:* 2026-02-27 *Status:* Accepted *Context:* Third-party panels +could be bad. PanLL shouldn’t take the blame. + +*Decision:* Two-tier trust model: + +[arabic] +. *PanLL Core is hash-locked* — TEA framework, Tea_Vdom, Tea_Html, panel +switcher, HAR are content-hashed. If core hashes don’t match: +`+CORE_HASH_MISMATCH+`, instantly detectable. Idris2 ABI layer makes +core provably correct. +. *Panels are author-signed* — Each panel manifest: +`+author: , signed: +`. PanLL doesn’t approve third-party +panels, just hosts them. Blame is cryptographically attributable. + +*Result:* Complaint is never "`PanLL is broken`". Either "`core hash is +wrong`" (tampered) or "`this panel is rubbish`" (author’s signature +proves it). + +''''' + +=== DD-010: Panel Taxonomy (Cladistic Classification) + +*Date:* 2026-03-02 *Status:* Accepted *Context:* Growing panel catalogue +needs organisation that invites contribution. + +*Decision:* Linnaean/cladistic hierarchy with EMPTY BRANCHES visible: + +[cols=",",options="header",] +|=== +|Level |Example +|Kingdom |Development, Operations, Governance, Analysis +|Phylum |Security, Languages, Databases, Infrastructure +|Class |Static Analysis, Runtime Monitoring, Formal Verification +|Order |Vulnerability Scanning, Compliance, Dependency Audit +|Family |Web Security, Network Security, Supply Chain +|Genus |Cloudflare Management, WordPress Hardening +|Species |CloudGuard, Wharf +|=== + +Empty nodes include metadata (description, expected Panel-L/N/W mapping, +suggested backend) — they’re specification slots, not stubs. +Contributors see gaps and naturally fill them. + +''''' + +=== DD-011: Notepad++ Community as First Target + +*Date:* 2026-03-02 *Status:* Accepted *Context:* Need first adopter +community that wants to extend, not replace. + +*Decision:* Target the Notepad++ community first: - Loyal, underserved +users who know their tool is limited - Not competing with VS Code’s +market - Extension culture — they already think in plugins - Metaphor: +PanLL doesn’t replace Notepad++ — it wraps around it. "`The bionic +Notepad++ user in a mech suit.`" + +''''' + +=== DD-012: Feedback-O-Tron as Opinion Mining System + +*Date:* 2026-03-02 *Status:* Proposed *Context:* Simple feedback form is +insufficient. Need structured sentiment analysis. + +*Decision:* Expand Feedback-O-Tron into three-tier system: 1. *Panel +Pulse* — Opinion mining that extracts structured sentiment from feedback +2. *Prioritisation engine* — Maps sentiment to panel development +priority 3. *Reusable infrastructure* — Same system usable by any +product, not just PanLL + +Connects to cognitive governance: Feedback-O-Tron → Vexometer → Humidity +→ UI adaptation. + +''''' + +=== DD-013: Triaxial Development Framework + +*Date:* 2026-03-02 *Status:* Accepted *Context:* Need a framework for +prioritising development work across the ecosystem. + +*Decision:* Three-axis scoring system: + +*Axis 1 — Scope* (what is wanted): - `+must+` (5) — Required for minimum +viable - `+intend+` (3) — Planned but deferrable - `+like+` (1) — Nice +to have + +*Axis 2 — Maintenance* (type of work): - `+corrective+` (5) — Fixing +something broken - `+adaptive+` (3) — Adapting to new requirements - +`+perfective+` (1) — Improving what works + +*Axis 3 — Audit* (what gets checked): - `+systems+` (5) — Core +architecture review - `+compliance+` (3) — Standards/policy check - +`+effects+` (1) — Impact assessment + +Combined score guides priority: must+corrective+systems = 15 (do +immediately), like+perfective+effects = 3 (backlog). + +''''' + +=== DD-014: FOSS-First Funding Strategy + +*Date:* 2026-03-02 *Status:* Accepted *Context:* Need sustainable +funding without compromising open source. + +*Decision:* Everything is MPL-2.0. Funding buys acceleration, not +access. The pitch: "`Is it really worth trying to compete with a crazy +academic, or just give him the money?`" The ecosystem is so far along +it’s cheaper to fund than to fork. + +''''' + +=== DD-015: ReScript Technical Patterns + +*Date:* 2026-03-02 *Status:* Accepted (standing reference) *Context:* +Lessons learned from building 107 ReScript files. + +*Key patterns:* - +`+Tea_Cmd.call(callbacks => { ... callbacks.enqueue(tagger(result)) ... })+` +for Tauri commands - `+@module("@tauri-apps/api/core") external invoke+` +for Tauri bindings - `+input(attrs, list{})+` — Tea_Html input takes 2 +args, not 1 - `+Attrs.ariaHidden(true)+` — takes bool, not string - +`+Attrs.style("width", "50%")+` — two args (key, value), not single +string - `+List.fromArray+` for array→list conversion - No emoji +literals in ReScript (use text like `+[V]+`, `+[!]+`) - Type constraints +in switch arms need parens: `+(Installed: panelInstallStatus)+` - +`+exception+` and `+constraint+` are reserved — use `+domainExc+` and +`+rule+` + +''''' + +=== DD-016: Code MRI — Mutual Recognition & Integrity + +*Date:* 2026-03-02 *Status:* Accepted *Context:* The Provenance Map +shows who wrote code (passive, read-only). Developers need to actively +annotate, attribute, and track the development process over time — for +transparency, education, diagnostics, and licensing compliance. + +*Decision:* Build Code MRI as a four-layer system integrated into PanLL +core: + +*Layer 0 — VoiceTag (Input)* Interactive annotation on code regions. +Voice-activated (Web Speech API, browser-native) but also works via +keyboard/mouse. Simple grammar: "`line 24 to 34 tag todo`", "`delete tag +7`", "`who wrote line 50`", "`attribute ai claude`". Tags are numbered +per file. Every tag records who created it (human voice, human keyboard, +AI agent, which AI). + +*Layer 1 — Blake3 Provenance Chain (Tamper Resistance)* Every code +region gets a Blake3 hash covering: content + author + timestamp + +parent hash. Imported code carries its provenance chain. Exported code +includes PanLL markings. Strip attribution? Hash mismatch — instantly +detectable. This is the Turnitin model flipped: collaborative +attribution, not adversarial plagiarism detection. + +*Layer 2 — VeriSimDB Development Timeline (Time Machine)* +Development-as-time-series database. Stores snapshots of: lines of code, +dangling TODOs/FIXMEs, open tags, libraries in use, failed type checks, +panic-attack findings, AI attribution percentage, Vexometer readings, +tag resolution time. Scrub a timeline slider to see the project state at +any point — like the end credits of a worldbuilder documentary. Active +rollback to any state within the database. + +*Layer 3 — Pattern Diagnostics & Gamification* Derive development +patterns from timeline data: "`this developer writes boilerplate +manually — slower but zero FIXMEs`", "`this AI session left 12 +unresolved tags — bullshit detector`", "`velocity increased 40% after +switching to ReScript.`" Victory conditions: all TODOs resolved, zero +panic-attack findings, Vexometer below threshold. Badges, streaks, +diagnostic not patronising. Admin enforcement mode for education +(universities can require attribution tracking on all submissions). + +*Layer 4 — Attribution-to-Licensing Link* PMPL (based on MPL) requires +source attribution. Blake3 provenance chains auto-generate license +attribution sections: "`Lines 1-50: Jonathan D.A. Jewell. Lines 51-80: +Claude Opus 4.6 (AI-assisted, human-reviewed). Lines 81-120: imported +from proven-servers (MPL-2.0).`" Makes source-available requirements +trivially verifiable. + +*The MRI Metaphor:* - Sees inside without being invasive (reads +blame/tags, doesn’t change code) - Shows layers at different resolutions +(file → region → line) - Diagnostic (reveals patterns invisible to +reading) - Non-destructive (code not altered by scanning) - Used by +professionals to make better decisions + +*Consequences:* - VoiceTag (Layer 0) is the thin end of the wedge — +buildable now, proves the concept - Blake3 chain (Layer 1) extends +existing Provenance Map infrastructure - VeriSimDB timeline (Layer 2) +dogfoods VeriSimDB as development analytics backend - Diagnostics (Layer +3) feeds Hypatia (pattern analysis) and Vexometer (friction) - License +link (Layer 4) makes PMPL compliance automatic, not manual - Admin mode +makes PanLL viable for educational institutions (Turnitin for code, but +honest) - Import/export of provenance markings makes attribution +portable across projects + +*Integration with existing PanLL:* - Provenance Map → Blake3 chain +(extends trust levels with tamper resistance) - Watcher → VoiceTag (file +changes trigger tag review prompts) - VeriSimDB → Timeline (dogfood the +database as development analytics store) - Hypatia → Diagnostics +(pattern analysis on development behaviour, not just code) - Vexometer → +Diagnostics (friction history is a timeline metric) - Provisioner → +Admin mode (configurable per panel, enforceable per organisation) + +''''' + +=== DD-017: Care-On / Eco-Mode Tags and Adaptive Constraint Sensitivity + +*Date:* 2026-03-02 *Status:* Accepted *Context:* Code regions have +different resource, ecological, and safety profiles. Developers need a +way to mark regions as resource-sensitive and have the system adapt its +behaviour accordingly — including adjusting the sensitivity of tools +like panic-attack. + +*Decision:* Extend VoiceTag with modal tags that change system +behaviour, not just annotate: + +*Tag modes:* - `+care-on+` — Mark a region as requiring extra scrutiny. +Raises panic-attack sensitivity, increases type checking strictness, +flags to agents as "`handle with care.`" For safety-critical code, +security-sensitive sections, or areas with known fragility. - +`+eco-mode+` — Mark a region as ecologically/resource non-viable. Flags +excessive allocation, energy-intensive loops, or computationally +wasteful patterns. Agents prioritise these for optimisation. The +triaxial framework scores eco-tagged regions higher on the +`+must × corrective × systems+` axis automatically. - `+burden+` — Mark +a constraint that is burdening the system. When panic-attack or type +checking generates too much noise in a region, `+burden+` says "`I know +this is a problem but the fix requires a serious rewrite — deprioritise +alerts here until the rewrite is scheduled.`" + +*How it works with the triaxial framework:* 1. Tags create triaxial +scoring adjustments automatically: `+eco-mode+` bumps scope to `+must+`, +maintenance to `+corrective+`, audit to `+systems+` (max priority) 2. +`+burden+` tags lower the audit axis to `+effects+` (acknowledged, not +ignored — just deprioritised) 3. `+care-on+` tags bump the audit axis to +`+systems+` (full scrutiny) 4. The priority queue rebalances: eco-risk +regions float to the top, burdened constraints sink to the backlog with +visibility + +*Adaptive sensitivity:* - panic-attack findings in `+care-on+` regions: +severity bumped one level (medium → high) - panic-attack findings in +`+burden+` regions: severity lowered one level (high → medium) with +"`[burden acknowledged]`" annotation - Agent behaviour: when operating +in `+eco-mode+` regions, agents optimise for resource efficiency first, +features second - Constraint tuning: if a type check or linter rule +generates >N findings in a `+burden+` region, auto-suppress with a +visible "`[N suppressed, burden tag active]`" counter + +*Consequences:* - Resource constraints become first-class development +concerns, not afterthoughts - Developers can tune system sensitivity per +region without global config changes - The triaxial framework adapts +automatically — no manual re-scoring needed - All tag changes are logged +in Code MRI timeline (visible, auditable, reversible) - Cheap to +implement: just additional tag types in VoiceTag + policy rules in the +matching engine + +''''' + +=== DD-018: Dogfood Mode — Self-Hosting Policy Engine + +*Date:* 2026-03-02 *Status:* Accepted *Context:* The hyperpolymath +ecosystem has 265+ repos of its own tooling. PanLL should actively +suggest using own tools where external alternatives are currently used, +with policy enforcement based on tool readiness. + +*Decision:* A dogfood management system with CRG-grade-driven policy: + +*Mechanism:* - Dogfood folder (configurable, default +`+~/Desktop/dogfood/+` or per-project `+.dogfood/+`): drop manifests +describing available internal tools - Matching engine: watches +imports/dependencies, suggests dogfood candidates when external +alternatives detected - Dashboard panel: which own tools are in use, +which are gathering dust, usage trends over time + +*Policy levels (driven by CRG grade):* - Grade D+ (Alpha): *Suggest* — +"`proven-servers has a TLS component, you’re using rustls directly`" - +Grade E (Minimal): *Warn* — "`QuandleDB is CRG E, proceed with caution`" +- Grade X/F (Untested/Harmful): *Ban* — "`Eclexia runtime is not ready, +blocked unless override`" - Admin override: "`I know this is grade E, +proceeding anyway`" (logged, visible in Code MRI) - *Insist*: +configurable per tool — "`Stapeln MUST be used for container isolation`" +(no override) + +*Consequences:* - D→C grade transition requires actual dogfooding — this +system tracks it - Feeds Code MRI timeline: "`switched from SQLite to +VeriSimDB on March 5`" - Connects to Provisioner: dogfood policies per +panel, per isolation tier - Custom dashboards: teams build their own +metrics ("`Mike’s Refactor Index`") - Research value: how developers +adopt their own tools, where friction appears + +''''' + +=== DD-022: Panel Capture — Screenshots, Recordings, and Demo Packages + +*Date:* 2026-03-02 *Status:* Accepted *Context:* Need integrated capture +system for screenshots, recordings, and demo/teaching packages within +PanLL panels. + +*Decision:* Capture module with Tauri backend providing: - Save +screenshot (any panel → PNG) - Print panel (formatted output) - Record +panel sessions - Demo package management (load/save/delete) + +*Implementation:* `+src/model/CaptureModel.res+` (types), +`+src/core/CaptureEngine.res+` (pure functions), +`+src-tauri/src/capture/+` (5 Tauri commands). + +''''' + +=== DD-024: Workspace Panel Management — Arrangements, Groups, and Sessions + +*Date:* 2026-03-02 *Status:* Accepted *Context:* Need persistent panel +arrangements, groups, sessions, and execution modes for multi-monitor +and multi-workflow support. + +*Decision:* Workspace management layer providing: - Named panel +arrangements (save/load to disk) - Panel groups with collective +operations - Session persistence and forking - Execution modes +(development, review, presentation) - Checkpoint/restore for workspace +state + +*Implementation:* `+src/model/WorkspaceModel.res+` (~230 lines), +`+src/core/WorkspaceEngine.res+` (~280 lines), +`+src-tauri/src/workspace/+` (7 Tauri commands including sysinfo). + +''''' + +=== DD-025: Configurable Status Bar Widget System + +*Date:* 2026-03-02 *Status:* Accepted *Context:* Need a flexible status +bar that displays system info, build status, and panel-specific widgets. + +*Decision:* Widget registry with positional layout: - Widget kinds: +text, icon, progress, separator, custom - Configurable positions and +visibility - System info integration (CPU, memory, disk) - Per-panel +status widgets + +*Implementation:* `+src/model/StatusBarModel.res+` (~75 lines), +`+src/core/StatusBarEngine.res+` (~170 lines, widget registry + +formatters). + +''''' + +=== DD-026: Security — Redaction and Vault + +*Date:* 2026-03-02 *Status:* Accepted *Context:* Panels display +sensitive data (API keys, credentials, secrets). Need integrated +redaction and vault. + +*Decision:* Security module providing: - Pattern-based redaction (regex +patterns for API keys, tokens, passwords) - Secret detection (scan panel +content for leaked credentials) - Vault storage (encrypted local vault +via Tauri) - Redaction modes: full, partial (show last 4), custom mask + +*Implementation:* `+src/model/SecurityModel.res+` (~140 lines), +`+src/core/SecurityEngine.res+` (~200 lines), +`+src-tauri/src/security/+` (5 Tauri commands). + +''''' + +=== DD-027: Security — 2FA and Trustfile Enforcement + +*Date:* 2026-03-02 *Status:* Accepted *Context:* Need second-factor +verification for destructive panel operations and Trustfile policy +enforcement. + +*Decision:* Integrated 2FA + Trustfile: - Two-factor gates for +destructive operations (delete, publish, deploy) - Trustfile enforcement +(PanLL reads `+.machine_readable/contractiles/trust/Trustfile.a2ml+`) - +Security level badges per panel (Kennel/Yard/Hunt from K9) - Audit log +of security-gated operations + +*Implementation:* Combined with DD-026 in `+src-tauri/src/security/+`. + +''''' + +_Design decisions are numbered sequentially. DD-019 through DD-021 and +DD-023 are reserved (not yet assigned). Superseded decisions retain +their number with status changed to "`Superseded by DD-XXX`"._ + +=== ADR-0001 (2026-05-17): panel-clades pivot + +SoT = `+panel-clades/+` (Idris2 ABI + Zig FFI + a2ml clades). +`+src-gossamer/+` Rust = frozen legacy. Coprocessor = Axiom.jl ’s +organising *approach* (not code); backends: FPGA, DSP, math, physics, +tensor, vector, I/O, audio, neural, crypto, quantum. oo7/jtv +experimental, out of scope. See +`+docs/decisions/ADR-0001-coprocessor-and-panel-clades-pivot.adoc+`. diff --git a/docs/decisions/DESIGN-DECISIONS.md b/docs/decisions/DESIGN-DECISIONS.md deleted file mode 100644 index 1a55cbe8..00000000 --- a/docs/decisions/DESIGN-DECISIONS.md +++ /dev/null @@ -1,483 +0,0 @@ - - -# PanLL Design Decisions - -**Last updated: 2026-03-02** -**Living document — updated as decisions are made or revised** - -## DD-001: eNSAID Is a Specification, PanLL Is an Implementation - -**Date:** 2026-02-27 -**Status:** Accepted -**Context:** Need to separate the idea from the tool so others can build competing implementations. - -**Decision:** eNSAID (Environment for NeSy-Agentic Integrated Development) is a specification. PanLL is the reference implementation. The spec lives in its own repo with its own governance. PanLL claims `IMPLEMENTS eNSAID` and that claim is verifiable. - -**Consequences:** -- Contributors contribute to the eNSAID ecosystem, not just PanLL -- Every panel written works with any compliant eNSAID environment -- Pattern: HTTP → Apache/Nginx/Caddy. SQL → Postgres/MySQL. LSP → every language server. -- If someone builds a better eNSAID, the idea survives - -**The V for Vendetta Principle:** You can kill PanLL. You cannot kill the idea. Ideas are bulletproof. - ---- - -## DD-002: Binary Star Architecture (Human-Machine Co-Orbit) - -**Date:** 2026-01-15 -**Status:** Accepted -**Context:** Traditional IDEs treat AI as subordinate tool. Need genuine co-working. - -**Decision:** Model Human and Machine as Binary Star system — two gravitationally bound entities orbiting a shared Barycentre (the task). Three panels: Panel-L (Symbolic/Human constraints), Panel-N (Neural/Machine reasoning), Panel-W (World/Barycentre results). Neither Human nor Machine is primary. - -**Consequences:** -- Operator sees Machine reasoning in real-time (Panel-N) -- Machine constrained by symbolic rules visible to both (Panel-L) -- Shared output space validates mutual understanding (Panel-W) -- Higher cognitive load initially, offset by Vexometer monitoring - ---- - -## DD-003: The Elm Architecture (TEA) for State Management - -**Date:** 2026-01-20 -**Status:** Accepted -**Context:** Complex UI with 14 panels, cognitive governance, orbital tracking needs deterministic state. - -**Decision:** Model-Update-View with Commands and Subscriptions. Single immutable model record. All state changes flow through typed messages. Custom TEA implementation extended for PanLL's needs. - -**Technical detail:** The main `model` type composes all domain slices via `include` re-exports. Each panel has its own Model/Engine/Cmd/Component files following a proven 8-file pattern. - ---- - -## DD-004: Panel Module Pattern (8 Files Per Panel) - -**Date:** 2026-03-01 -**Status:** Accepted -**Context:** Need a repeatable, consistent pattern for adding panels. - -**Decision:** Every panel follows exactly 8 files: - -| Layer | ReScript | Rust (if backend needed) | -|-------|----------|--------------------------| -| Types | `src/model/XModel.res` | `src-tauri/src/x/types.rs` | -| Engine | `src/core/XEngine.res` | — | -| Commands | `src/commands/XCmd.res` | `src-tauri/src/x/commands.rs` | -| Component | `src/components/X.res` | `src-tauri/src/x/mod.rs` | - -Plus wiring into 5 global files: Msg.res, Model.res, Update.res, View.res, main.rs - -**Consequences:** -- Panel Minter can generate this structure automatically -- Every panel is structurally identical — contributors know where everything is -- Engine files are pure functions (no side effects) — fully testable -- Cmd files handle Tauri IPC — all effects isolated - ---- - -## DD-005: Three-Tier Panel Isolation (Native / Standard Pod / Hardened Pod) - -**Date:** 2026-03-02 -**Status:** Accepted -**Context:** Third-party panels could be malicious or poorly written. Core panels should run fast. - -**Decision:** Three isolation tiers, selectable per panel via the Provisioner: - -| Tier | Runtime | Security | Performance | Use Case | -|------|---------|----------|-------------|----------| -| **Native** | In-process (Tauri webview) | Full trust, hash-verified | Fastest | Core 14 panels | -| **Standard Pod** | Alpine + Podman container | Process isolation, network limited | Moderate overhead | Community panels, trusted | -| **Hardened Pod** | Stapeln + Chainguard image | Full Stapeln security stack, minimal attack surface | Higher overhead | Untrusted/experimental panels | - -**Consequences:** -- Core panels default to Native (no container overhead) -- Community panels default to StandardPod -- Users can override in Provisioner Configurator tab -- Clean uninstall: delete the pod, everything goes -- Supply chain commitment: containers are not just security, they're reversibility - ---- - -## DD-006: Qubes-Style Code Provenance Map - -**Date:** 2026-03-02 -**Status:** Accepted -**Context:** Need to show who wrote each line and how trustworthy it is. - -**Decision:** Always-visible ambient trust surface (not a toggle). Parses git blame + Co-Authored-By headers. Fixed semantic colour meanings: - -| Level | Colour | Meaning | Detection | -|-------|--------|---------|-----------| -| Verified | Green | Formally verified, proof-checked, no believe_me | Proof markers in commit | -| Human-Reviewed | Blue | Human author or human commit after AI | No co-author, or subsequent human commit | -| AI-Assisted | Amber | Co-authored, no subsequent human review | Co-Authored-By present, no later human commit | -| Unreviewed AI | Red | Pure AI, no human in chain | AI author, no human review | -| Unknown | Grey | Pre-git or no attribution | No blame data available | - -**Key constraint:** Colours swap hues for accessibility palettes (4 palettes: Standard, Deuteranopia, Protanopia, High Contrast) but NEVER swap meanings. Green always means verified, regardless of the actual hue displayed. - -**Hostile UX:** Unreviewed AI code gets pulsing red borders and increased visual friction. Users CAN suppress this, but the suppression action is itself visible ("pulled the smoke alarm battery"). - ---- - -## DD-007: Cognitive Governance Stack - -**Date:** 2026-01-25 -**Status:** Accepted -**Context:** Co-orbit increases cognitive load. Need automated monitoring. - -**Decision:** Four interconnected governance systems: - -1. **Anti-Crash Gate** — Circuit breaker between Panel-N output and Panel-W workspace. Every neural token validated against Panel-L constraints before reaching shared space. -2. **Vexometer** — Friction monitor tracking cancellations, corrections, dwell time. Index 0.0–1.0 triggers anti-inflammatory UI adjustments. -3. **Information Humidity** — UI density adapts to stress. High humidity (relaxed) = more detail. Low humidity (stressed) = essential info only. -4. **Orbital Drift Aura** — Ambient visual (background colour shift) indicating system stability. Visible without looking at any specific panel. - -These feed each other: Feedback-O-Tron → Vexometer → Humidity → UI adaptation. - ---- - -## DD-008: Accessibility as Core, Not Afterthought - -**Date:** 2026-02-27 -**Status:** Accepted -**Context:** Accessibility is usually bolted on after launch. PanLL should be different. - -**Decision:** Accessibility is in the CORE infrastructure, not in individual panels: -- Panel Minter produces accessible panels by default (harder to make inaccessible than accessible) -- Every colour system ships with 4 accessibility palettes -- Every keyboard interaction works without a mouse -- Screen reader semantics (ARIA) in every component template -- Renamed broader concept to "information/cognitive ergonomics" (accessibility is a subset) - -**The discipline covers:** -- Perceptual load management (how much information before overload) -- Cognitive friction reduction (Vexometer measures this) -- Task-flow preservation (panels don't interrupt flow) -- Multi-modal presentation (visual + auditory + haptic) -- Expertise scaffolding (novice → expert gradual complexity reveal) - ---- - -## DD-009: Trust & Blame Separation - -**Date:** 2026-02-27 -**Status:** Accepted -**Context:** Third-party panels could be bad. PanLL shouldn't take the blame. - -**Decision:** Two-tier trust model: - -1. **PanLL Core is hash-locked** — TEA framework, Tea_Vdom, Tea_Html, panel switcher, HAR are content-hashed. If core hashes don't match: `CORE_HASH_MISMATCH`, instantly detectable. Idris2 ABI layer makes core provably correct. - -2. **Panels are author-signed** — Each panel manifest: `author: , signed: `. PanLL doesn't approve third-party panels, just hosts them. Blame is cryptographically attributable. - -**Result:** Complaint is never "PanLL is broken". Either "core hash is wrong" (tampered) or "this panel is rubbish" (author's signature proves it). - ---- - -## DD-010: Panel Taxonomy (Cladistic Classification) - -**Date:** 2026-03-02 -**Status:** Accepted -**Context:** Growing panel catalogue needs organisation that invites contribution. - -**Decision:** Linnaean/cladistic hierarchy with EMPTY BRANCHES visible: - -| Level | Example | -|-------|---------| -| Kingdom | Development, Operations, Governance, Analysis | -| Phylum | Security, Languages, Databases, Infrastructure | -| Class | Static Analysis, Runtime Monitoring, Formal Verification | -| Order | Vulnerability Scanning, Compliance, Dependency Audit | -| Family | Web Security, Network Security, Supply Chain | -| Genus | Cloudflare Management, WordPress Hardening | -| Species | CloudGuard, Wharf | - -Empty nodes include metadata (description, expected Panel-L/N/W mapping, suggested backend) — they're specification slots, not stubs. Contributors see gaps and naturally fill them. - ---- - -## DD-011: Notepad++ Community as First Target - -**Date:** 2026-03-02 -**Status:** Accepted -**Context:** Need first adopter community that wants to extend, not replace. - -**Decision:** Target the Notepad++ community first: -- Loyal, underserved users who know their tool is limited -- Not competing with VS Code's market -- Extension culture — they already think in plugins -- Metaphor: PanLL doesn't replace Notepad++ — it wraps around it. "The bionic Notepad++ user in a mech suit." - ---- - -## DD-012: Feedback-O-Tron as Opinion Mining System - -**Date:** 2026-03-02 -**Status:** Proposed -**Context:** Simple feedback form is insufficient. Need structured sentiment analysis. - -**Decision:** Expand Feedback-O-Tron into three-tier system: -1. **Panel Pulse** — Opinion mining that extracts structured sentiment from feedback -2. **Prioritisation engine** — Maps sentiment to panel development priority -3. **Reusable infrastructure** — Same system usable by any product, not just PanLL - -Connects to cognitive governance: Feedback-O-Tron → Vexometer → Humidity → UI adaptation. - ---- - -## DD-013: Triaxial Development Framework - -**Date:** 2026-03-02 -**Status:** Accepted -**Context:** Need a framework for prioritising development work across the ecosystem. - -**Decision:** Three-axis scoring system: - -**Axis 1 — Scope** (what is wanted): -- `must` (5) — Required for minimum viable -- `intend` (3) — Planned but deferrable -- `like` (1) — Nice to have - -**Axis 2 — Maintenance** (type of work): -- `corrective` (5) — Fixing something broken -- `adaptive` (3) — Adapting to new requirements -- `perfective` (1) — Improving what works - -**Axis 3 — Audit** (what gets checked): -- `systems` (5) — Core architecture review -- `compliance` (3) — Standards/policy check -- `effects` (1) — Impact assessment - -Combined score guides priority: must+corrective+systems = 15 (do immediately), like+perfective+effects = 3 (backlog). - ---- - -## DD-014: FOSS-First Funding Strategy - -**Date:** 2026-03-02 -**Status:** Accepted -**Context:** Need sustainable funding without compromising open source. - -**Decision:** Everything is MPL-2.0. Funding buys acceleration, not access. The pitch: "Is it really worth trying to compete with a crazy academic, or just give him the money?" The ecosystem is so far along it's cheaper to fund than to fork. - ---- - -## DD-015: ReScript Technical Patterns - -**Date:** 2026-03-02 -**Status:** Accepted (standing reference) -**Context:** Lessons learned from building 107 ReScript files. - -**Key patterns:** -- `Tea_Cmd.call(callbacks => { ... callbacks.enqueue(tagger(result)) ... })` for Tauri commands -- `@module("@tauri-apps/api/core") external invoke` for Tauri bindings -- `input(attrs, list{})` — Tea_Html input takes 2 args, not 1 -- `Attrs.ariaHidden(true)` — takes bool, not string -- `Attrs.style("width", "50%")` — two args (key, value), not single string -- `List.fromArray` for array→list conversion -- No emoji literals in ReScript (use text like `[V]`, `[!]`) -- Type constraints in switch arms need parens: `(Installed: panelInstallStatus)` -- `exception` and `constraint` are reserved — use `domainExc` and `rule` - ---- - -## DD-016: Code MRI — Mutual Recognition & Integrity - -**Date:** 2026-03-02 -**Status:** Accepted -**Context:** The Provenance Map shows who wrote code (passive, read-only). Developers need to actively annotate, attribute, and track the development process over time — for transparency, education, diagnostics, and licensing compliance. - -**Decision:** Build Code MRI as a four-layer system integrated into PanLL core: - -**Layer 0 — VoiceTag (Input)** -Interactive annotation on code regions. Voice-activated (Web Speech API, browser-native) but also works via keyboard/mouse. Simple grammar: "line 24 to 34 tag todo", "delete tag 7", "who wrote line 50", "attribute ai claude". Tags are numbered per file. Every tag records who created it (human voice, human keyboard, AI agent, which AI). - -**Layer 1 — Blake3 Provenance Chain (Tamper Resistance)** -Every code region gets a Blake3 hash covering: content + author + timestamp + parent hash. Imported code carries its provenance chain. Exported code includes PanLL markings. Strip attribution? Hash mismatch — instantly detectable. This is the Turnitin model flipped: collaborative attribution, not adversarial plagiarism detection. - -**Layer 2 — VeriSimDB Development Timeline (Time Machine)** -Development-as-time-series database. Stores snapshots of: lines of code, dangling TODOs/FIXMEs, open tags, libraries in use, failed type checks, panic-attack findings, AI attribution percentage, Vexometer readings, tag resolution time. Scrub a timeline slider to see the project state at any point — like the end credits of a worldbuilder documentary. Active rollback to any state within the database. - -**Layer 3 — Pattern Diagnostics & Gamification** -Derive development patterns from timeline data: "this developer writes boilerplate manually — slower but zero FIXMEs", "this AI session left 12 unresolved tags — bullshit detector", "velocity increased 40% after switching to ReScript." Victory conditions: all TODOs resolved, zero panic-attack findings, Vexometer below threshold. Badges, streaks, diagnostic not patronising. Admin enforcement mode for education (universities can require attribution tracking on all submissions). - -**Layer 4 — Attribution-to-Licensing Link** -PMPL (based on MPL) requires source attribution. Blake3 provenance chains auto-generate license attribution sections: "Lines 1-50: Jonathan D.A. Jewell. Lines 51-80: Claude Opus 4.6 (AI-assisted, human-reviewed). Lines 81-120: imported from proven-servers (MPL-2.0)." Makes source-available requirements trivially verifiable. - -**The MRI Metaphor:** -- Sees inside without being invasive (reads blame/tags, doesn't change code) -- Shows layers at different resolutions (file → region → line) -- Diagnostic (reveals patterns invisible to reading) -- Non-destructive (code not altered by scanning) -- Used by professionals to make better decisions - -**Consequences:** -- VoiceTag (Layer 0) is the thin end of the wedge — buildable now, proves the concept -- Blake3 chain (Layer 1) extends existing Provenance Map infrastructure -- VeriSimDB timeline (Layer 2) dogfoods VeriSimDB as development analytics backend -- Diagnostics (Layer 3) feeds Hypatia (pattern analysis) and Vexometer (friction) -- License link (Layer 4) makes PMPL compliance automatic, not manual -- Admin mode makes PanLL viable for educational institutions (Turnitin for code, but honest) -- Import/export of provenance markings makes attribution portable across projects - -**Integration with existing PanLL:** -- Provenance Map → Blake3 chain (extends trust levels with tamper resistance) -- Watcher → VoiceTag (file changes trigger tag review prompts) -- VeriSimDB → Timeline (dogfood the database as development analytics store) -- Hypatia → Diagnostics (pattern analysis on development behaviour, not just code) -- Vexometer → Diagnostics (friction history is a timeline metric) -- Provisioner → Admin mode (configurable per panel, enforceable per organisation) - ---- - -## DD-017: Care-On / Eco-Mode Tags and Adaptive Constraint Sensitivity - -**Date:** 2026-03-02 -**Status:** Accepted -**Context:** Code regions have different resource, ecological, and safety profiles. Developers need a way to mark regions as resource-sensitive and have the system adapt its behaviour accordingly — including adjusting the sensitivity of tools like panic-attack. - -**Decision:** Extend VoiceTag with modal tags that change system behaviour, not just annotate: - -**Tag modes:** -- `care-on` — Mark a region as requiring extra scrutiny. Raises panic-attack sensitivity, increases type checking strictness, flags to agents as "handle with care." For safety-critical code, security-sensitive sections, or areas with known fragility. -- `eco-mode` — Mark a region as ecologically/resource non-viable. Flags excessive allocation, energy-intensive loops, or computationally wasteful patterns. Agents prioritise these for optimisation. The triaxial framework scores eco-tagged regions higher on the `must × corrective × systems` axis automatically. -- `burden` — Mark a constraint that is burdening the system. When panic-attack or type checking generates too much noise in a region, `burden` says "I know this is a problem but the fix requires a serious rewrite — deprioritise alerts here until the rewrite is scheduled." - -**How it works with the triaxial framework:** -1. Tags create triaxial scoring adjustments automatically: `eco-mode` bumps scope to `must`, maintenance to `corrective`, audit to `systems` (max priority) -2. `burden` tags lower the audit axis to `effects` (acknowledged, not ignored — just deprioritised) -3. `care-on` tags bump the audit axis to `systems` (full scrutiny) -4. The priority queue rebalances: eco-risk regions float to the top, burdened constraints sink to the backlog with visibility - -**Adaptive sensitivity:** -- panic-attack findings in `care-on` regions: severity bumped one level (medium → high) -- panic-attack findings in `burden` regions: severity lowered one level (high → medium) with "[burden acknowledged]" annotation -- Agent behaviour: when operating in `eco-mode` regions, agents optimise for resource efficiency first, features second -- Constraint tuning: if a type check or linter rule generates >N findings in a `burden` region, auto-suppress with a visible "[N suppressed, burden tag active]" counter - -**Consequences:** -- Resource constraints become first-class development concerns, not afterthoughts -- Developers can tune system sensitivity per region without global config changes -- The triaxial framework adapts automatically — no manual re-scoring needed -- All tag changes are logged in Code MRI timeline (visible, auditable, reversible) -- Cheap to implement: just additional tag types in VoiceTag + policy rules in the matching engine - ---- - -## DD-018: Dogfood Mode — Self-Hosting Policy Engine - -**Date:** 2026-03-02 -**Status:** Accepted -**Context:** The hyperpolymath ecosystem has 265+ repos of its own tooling. PanLL should actively suggest using own tools where external alternatives are currently used, with policy enforcement based on tool readiness. - -**Decision:** A dogfood management system with CRG-grade-driven policy: - -**Mechanism:** -- Dogfood folder (configurable, default `~/Desktop/dogfood/` or per-project `.dogfood/`): drop manifests describing available internal tools -- Matching engine: watches imports/dependencies, suggests dogfood candidates when external alternatives detected -- Dashboard panel: which own tools are in use, which are gathering dust, usage trends over time - -**Policy levels (driven by CRG grade):** -- Grade D+ (Alpha): **Suggest** — "proven-servers has a TLS component, you're using rustls directly" -- Grade E (Minimal): **Warn** — "QuandleDB is CRG E, proceed with caution" -- Grade X/F (Untested/Harmful): **Ban** — "Eclexia runtime is not ready, blocked unless override" -- Admin override: "I know this is grade E, proceeding anyway" (logged, visible in Code MRI) -- **Insist**: configurable per tool — "Stapeln MUST be used for container isolation" (no override) - -**Consequences:** -- D→C grade transition requires actual dogfooding — this system tracks it -- Feeds Code MRI timeline: "switched from SQLite to VeriSimDB on March 5" -- Connects to Provisioner: dogfood policies per panel, per isolation tier -- Custom dashboards: teams build their own metrics ("Mike's Refactor Index") -- Research value: how developers adopt their own tools, where friction appears - ---- - -## DD-022: Panel Capture — Screenshots, Recordings, and Demo Packages - -**Date:** 2026-03-02 -**Status:** Accepted -**Context:** Need integrated capture system for screenshots, recordings, and demo/teaching packages within PanLL panels. - -**Decision:** Capture module with Tauri backend providing: -- Save screenshot (any panel → PNG) -- Print panel (formatted output) -- Record panel sessions -- Demo package management (load/save/delete) - -**Implementation:** `src/model/CaptureModel.res` (types), `src/core/CaptureEngine.res` (pure functions), `src-tauri/src/capture/` (5 Tauri commands). - ---- - -## DD-024: Workspace Panel Management — Arrangements, Groups, and Sessions - -**Date:** 2026-03-02 -**Status:** Accepted -**Context:** Need persistent panel arrangements, groups, sessions, and execution modes for multi-monitor and multi-workflow support. - -**Decision:** Workspace management layer providing: -- Named panel arrangements (save/load to disk) -- Panel groups with collective operations -- Session persistence and forking -- Execution modes (development, review, presentation) -- Checkpoint/restore for workspace state - -**Implementation:** `src/model/WorkspaceModel.res` (~230 lines), `src/core/WorkspaceEngine.res` (~280 lines), `src-tauri/src/workspace/` (7 Tauri commands including sysinfo). - ---- - -## DD-025: Configurable Status Bar Widget System - -**Date:** 2026-03-02 -**Status:** Accepted -**Context:** Need a flexible status bar that displays system info, build status, and panel-specific widgets. - -**Decision:** Widget registry with positional layout: -- Widget kinds: text, icon, progress, separator, custom -- Configurable positions and visibility -- System info integration (CPU, memory, disk) -- Per-panel status widgets - -**Implementation:** `src/model/StatusBarModel.res` (~75 lines), `src/core/StatusBarEngine.res` (~170 lines, widget registry + formatters). - ---- - -## DD-026: Security — Redaction and Vault - -**Date:** 2026-03-02 -**Status:** Accepted -**Context:** Panels display sensitive data (API keys, credentials, secrets). Need integrated redaction and vault. - -**Decision:** Security module providing: -- Pattern-based redaction (regex patterns for API keys, tokens, passwords) -- Secret detection (scan panel content for leaked credentials) -- Vault storage (encrypted local vault via Tauri) -- Redaction modes: full, partial (show last 4), custom mask - -**Implementation:** `src/model/SecurityModel.res` (~140 lines), `src/core/SecurityEngine.res` (~200 lines), `src-tauri/src/security/` (5 Tauri commands). - ---- - -## DD-027: Security — 2FA and Trustfile Enforcement - -**Date:** 2026-03-02 -**Status:** Accepted -**Context:** Need second-factor verification for destructive panel operations and Trustfile policy enforcement. - -**Decision:** Integrated 2FA + Trustfile: -- Two-factor gates for destructive operations (delete, publish, deploy) -- Trustfile enforcement (PanLL reads `.machine_readable/contractiles/trust/Trustfile.a2ml`) -- Security level badges per panel (Kennel/Yard/Hunt from K9) -- Audit log of security-gated operations - -**Implementation:** Combined with DD-026 in `src-tauri/src/security/`. - ---- - -*Design decisions are numbered sequentially. DD-019 through DD-021 and DD-023 are reserved (not yet assigned). Superseded decisions retain their number with status changed to "Superseded by DD-XXX".* - -## ADR-0001 (2026-05-17): panel-clades pivot - -SoT = `panel-clades/` (Idris2 ABI + Zig FFI + a2ml clades). `src-gossamer/` Rust = frozen legacy. Coprocessor = Axiom.jl 's organising **approach** (not code); backends: FPGA, DSP, math, physics, tensor, vector, I/O, audio, neural, crypto, quantum. oo7/jtv experimental, out of scope. See `docs/decisions/ADR-0001-coprocessor-and-panel-clades-pivot.adoc`. diff --git a/docs/decisions/PANLL-ENSAID-SPEC-AND-DESIGN-DECISIONS.adoc b/docs/decisions/PANLL-ENSAID-SPEC-AND-DESIGN-DECISIONS.adoc new file mode 100644 index 00000000..2e483976 --- /dev/null +++ b/docs/decisions/PANLL-ENSAID-SPEC-AND-DESIGN-DECISIONS.adoc @@ -0,0 +1,562 @@ +== PanLL eNSAID Specification & Design Decisions + +*Compiled: 2026-03-14* *Source: panll/docs/DESIGN-DECISIONS.md + +panll/docs/DESIGN-2026-03-08-idaptik-ensaid.md* + +''''' + +== PART 1: eNSAID DESIGN DECISIONS (DD-001 to DD-018) + +*Last updated: 2026-03-02* *Living document — updated as decisions are +made or revised* + +=== DD-001: eNSAID Is a Specification, PanLL Is an Implementation + +*Date:* 2026-02-27 *Status:* Accepted *Context:* Need to separate the +idea from the tool so others can build competing implementations. + +*Decision:* eNSAID (Environment for NeSy-Agentic Integrated Development) +is a specification. PanLL is the reference implementation. The spec +lives in its own repo with its own governance. PanLL claims +`+IMPLEMENTS eNSAID+` and that claim is verifiable. + +*Consequences:* - Contributors contribute to the eNSAID ecosystem, not +just PanLL - Every panel written works with any compliant eNSAID +environment - Pattern: HTTP → Apache/Nginx/Caddy. SQL → Postgres/MySQL. +LSP → every language server. - If someone builds a better eNSAID, the +idea survives + +*The V for Vendetta Principle:* You can kill PanLL. You cannot kill the +idea. Ideas are bulletproof. + +''''' + +=== DD-002: Binary Star Architecture (Human-Machine Co-Orbit) + +*Date:* 2026-01-15 *Status:* Accepted *Context:* Traditional IDEs treat +AI as subordinate tool. Need genuine co-working. + +*Decision:* Model Human and Machine as Binary Star system — two +gravitationally bound entities orbiting a shared Barycentre (the task). +Three panels: Panel-L (Symbolic/Human constraints), Panel-N +(Neural/Machine reasoning), Panel-W (World/Barycentre results). Neither +Human nor Machine is primary. + +*Consequences:* - Operator sees Machine reasoning in real-time (Panel-N) +- Machine constrained by symbolic rules visible to both (Panel-L) - +Shared output space validates mutual understanding (Panel-W) - Higher +cognitive load initially, offset by Vexometer monitoring + +''''' + +=== DD-003: The Elm Architecture (TEA) for State Management + +*Date:* 2026-01-20 *Status:* Accepted *Context:* Complex UI with 14 +panels, cognitive governance, orbital tracking needs deterministic +state. + +*Decision:* Model-Update-View with Commands and Subscriptions. Single +immutable model record. All state changes flow through typed messages. +Custom TEA implementation extended for PanLL’s needs. + +*Technical detail:* The main `+model+` type composes all domain slices +via `+include+` re-exports. Each panel has its own +Model/Engine/Cmd/Component files following a proven 8-file pattern. + +''''' + +=== DD-004: Panel Module Pattern (8 Files Per Panel) + +*Date:* 2026-03-01 *Status:* Accepted *Context:* Need a repeatable, +consistent pattern for adding panels. + +*Decision:* Every panel follows exactly 8 files: + +[cols=",,",options="header",] +|=== +|Layer |ReScript |Rust (if backend needed) +|Types |`+src/model/XModel.res+` |`+src-tauri/src/x/types.rs+` +|Engine |`+src/core/XEngine.res+` |— +|Commands |`+src/commands/XCmd.res+` |`+src-tauri/src/x/commands.rs+` +|Component |`+src/components/X.res+` |`+src-tauri/src/x/mod.rs+` +|=== + +Plus wiring into 5 global files: Msg.res, Model.res, Update.res, +View.res, main.rs + +*Consequences:* - Panel Minter can generate this structure automatically +- Every panel is structurally identical — contributors know where +everything is - Engine files are pure functions (no side effects) — +fully testable - Cmd files handle Tauri IPC — all effects isolated + +''''' + +=== DD-005: Three-Tier Panel Isolation (Native / Standard Pod / Hardened Pod) + +*Date:* 2026-03-02 *Status:* Accepted + +[width="100%",cols="15%,18%,20%,27%,20%",options="header",] +|=== +|Tier |Runtime |Security |Performance |Use Case +|*Native* |In-process (Tauri webview) |Full trust, hash-verified +|Fastest |Core 14 panels + +|*Standard Pod* |Alpine + Podman container |Process isolation, network +limited |Moderate overhead |Community panels, trusted + +|*Hardened Pod* |Stapeln + Chainguard image |Full Stapeln security +stack, minimal attack surface |Higher overhead |Untrusted/experimental +panels +|=== + +''''' + +=== DD-006: Qubes-Style Code Provenance Map + +*Date:* 2026-03-02 *Status:* Accepted + +Always-visible ambient trust surface (not a toggle). Parses git blame + +Co-Authored-By headers. + +[cols=",,",options="header",] +|=== +|Level |Colour |Meaning +|Verified |Green |Formally verified, proof-checked, no believe_me +|Human-Reviewed |Blue |Human author or human commit after AI +|AI-Assisted |Amber |Co-authored, no subsequent human review +|Unreviewed AI |Red |Pure AI, no human in chain +|Unknown |Grey |Pre-git or no attribution +|=== + +*Hostile UX:* Unreviewed AI code gets pulsing red borders and increased +visual friction. Users CAN suppress this, but the suppression action is +itself visible ("`pulled the smoke alarm battery`"). + +''''' + +=== DD-007: Cognitive Governance Stack + +*Date:* 2026-01-25 *Status:* Accepted + +Four interconnected governance systems: + +[arabic] +. *Anti-Crash Gate* — Circuit breaker between Panel-N output and Panel-W +workspace. Every neural token validated against Panel-L constraints +before reaching shared space. +. *Vexometer* — Friction monitor tracking cancellations, corrections, +dwell time. Index 0.0–1.0 triggers anti-inflammatory UI adjustments. +. *Information Humidity* — UI density adapts to stress. High humidity +(relaxed) = more detail. Low humidity (stressed) = essential info only. +. *Orbital Drift Aura* — Ambient visual (background colour shift) +indicating system stability. + +These feed each other: Feedback-O-Tron → Vexometer → Humidity → UI +adaptation. + +''''' + +=== DD-008: Accessibility as Core, Not Afterthought + +*Date:* 2026-02-27 *Status:* Accepted + +Accessibility is in the CORE infrastructure: - Panel Minter produces +accessible panels by default (harder to make inaccessible than +accessible) - Every colour system ships with 4 accessibility palettes - +Every keyboard interaction works without a mouse - Screen reader +semantics (ARIA) in every component template - Renamed broader concept +to "`information/cognitive ergonomics`" + +''''' + +=== DD-009: Trust & Blame Separation + +*Date:* 2026-02-27 *Status:* Accepted + +Two-tier trust model: + +[arabic] +. *PanLL Core is hash-locked* — TEA framework, Tea_Vdom, Tea_Html, panel +switcher, HAR are content-hashed. If core hashes don’t match: +`+CORE_HASH_MISMATCH+`, instantly detectable. +. *Panels are author-signed* — Each panel manifest: +`+author: , signed: +`. PanLL doesn’t approve third-party +panels, just hosts them. Blame is cryptographically attributable. + +''''' + +=== DD-010: Panel Taxonomy (Cladistic Classification) + +*Date:* 2026-03-02 *Status:* Accepted + +Linnaean/cladistic hierarchy with EMPTY BRANCHES visible: + +[cols=",",options="header",] +|=== +|Level |Example +|Kingdom |Development, Operations, Governance, Analysis +|Phylum |Security, Languages, Databases, Infrastructure +|Class |Static Analysis, Runtime Monitoring, Formal Verification +|Order |Vulnerability Scanning, Compliance, Dependency Audit +|Family |Web Security, Network Security, Supply Chain +|Genus |Cloudflare Management, WordPress Hardening +|Species |CloudGuard, Wharf +|=== + +Empty nodes are specification slots, not stubs. Contributors see gaps +and naturally fill them. + +''''' + +=== DD-011: Notepad++ Community as First Target + +*Date:* 2026-03-02 *Status:* Accepted + +Target the Notepad++ community first. Metaphor: PanLL doesn’t replace +Notepad++ — it wraps around it. "`The bionic Notepad++ user in a mech +suit.`" + +''''' + +=== DD-012: Feedback-O-Tron as Opinion Mining System + +*Date:* 2026-03-02 *Status:* Proposed + +Three-tier system: 1. *Panel Pulse* — Opinion mining extracts structured +sentiment from feedback 2. *Prioritisation engine* — Maps sentiment to +panel development priority 3. *Reusable infrastructure* — Same system +usable by any product, not just PanLL + +''''' + +=== DD-013: Triaxial Development Framework (TSDM) + +*Date:* 2026-03-02 *Status:* Accepted + +*Axis 1 — Scope:* must (5), intend (3), like (1) *Axis 2 — Maintenance:* +corrective (5), adaptive (3), perfective (1) *Axis 3 — Audit:* systems +(5), compliance (3), effects (1) + +Combined score: must+corrective+systems = 15 (do immediately), +like+perfective+effects = 3 (backlog). + +''''' + +=== DD-014: FOSS-First Funding Strategy + +*Date:* 2026-03-02 *Status:* Accepted + +Everything is MPL-2.0. Funding buys acceleration, not access. "`Is it +really worth trying to compete with a crazy academic, or just give him +the money?`" + +''''' + +=== DD-015: ReScript Technical Patterns + +*Date:* 2026-03-02 *Status:* Accepted (standing reference) + +Key patterns: - +`+Tea_Cmd.call(callbacks => { ... callbacks.enqueue(tagger(result)) ... })+` +for Tauri commands - `+@module("@tauri-apps/api/core") external invoke+` +for Tauri bindings - `+input(attrs, list{})+` — Tea_Html input takes 2 +args, not 1 - `+Attrs.style("width", "50%")+` — two args (key, value), +not single string - No emoji literals in ReScript - `+exception+` and +`+constraint+` are reserved — use `+domainExc+` and `+rule+` + +''''' + +=== DD-016: Code MRI — Mutual Recognition & Integrity + +*Date:* 2026-03-02 *Status:* Accepted + +Four-layer system: + +*Layer 0 — VoiceTag (Input):* Interactive annotation on code regions. +Voice-activated (Web Speech API) but also keyboard/mouse. Tags numbered +per file. + +*Layer 1 — Blake3 Provenance Chain:* Every code region gets a Blake3 +hash covering content + author + timestamp + parent hash. Strip +attribution? Hash mismatch — instantly detectable. Turnitin model +flipped: collaborative attribution, not adversarial plagiarism +detection. + +*Layer 2 — VeriSimDB Development Timeline:* Development-as-time-series +database. Scrub a timeline slider to see the project state at any point +— like the end credits of a worldbuilder documentary. + +*Layer 3 — Pattern Diagnostics & Gamification:* Derive development +patterns from timeline data. Victory conditions: all TODOs resolved, +zero panic-attack findings, Vexometer below threshold. + +*Layer 4 — Attribution-to-Licensing Link:* Blake3 provenance chains +auto-generate license attribution sections. + +''''' + +=== DD-017: Care-On / Eco-Mode Tags and Adaptive Constraint Sensitivity + +*Date:* 2026-03-02 *Status:* Accepted + +Tag modes: - `+care-on+` — Extra scrutiny. Raises panic-attack +sensitivity. - `+eco-mode+` — Flags excessive allocation, +energy-intensive loops. - `+burden+` — "`I know this is a problem but +the fix requires a serious rewrite.`" + +Integrates with triaxial framework: eco-mode bumps to max priority, +burden lowers audit axis. + +''''' + +=== DD-018: Dogfood Mode — Self-Hosting Policy Engine + +*Date:* 2026-03-02 *Status:* Accepted + +Dogfood management with CRG-grade-driven policy: - Grade D+ (Alpha): +*Suggest* - Grade E (Minimal): *Warn* - Grade X/F (Untested/Harmful): +*Ban* - *Insist*: configurable per tool (no override) + +''''' + +''''' + +== PART 2: PanLL as eNSAID for IDApTIK Development + +*Date*: 2026-03-08 *Author*: Jonathan D.A. Jewell +j.d.a.jewell@open.ac.uk *Status*: Design (MuSCoCA-classified) + +=== Overview + +This document designs PanLL as an *eNSAID* (Environment for NeSy-Agentic +Integrated Development) tailored for IDApTIK game development — a +collaborative parent-child workbench where Jonathan and his son can +build, test, debug, visualise, and evolve the IDApixiTIK game together. + +The key insight: IDApTIK is a *reversible-computation stealth puzzle +game* with a VM, multiplayer sync server, coprocessor system, device +network topology, and formal verification layer. PanLL’s three-panel +neurosymbolic model maps directly onto this: + +[width="100%",cols="44%,56%",options="header",] +|=== +|PanLL Panel |IDApTIK Mapping +|*Panel-L* (Symbolic) |VM instruction constraints, level rules, device +defence flags, protocol specs + +|*Panel-N* (Neural) |ECHIDNA proof advisor for VM correctness, +AI-assisted level design, NeSy reasoning + +|*Panel-W* (World) |Game preview, network topology view, device +dashboard, telemetry +|=== + +''''' + +=== The IDApTIK Panel Suite (11 panels) + +==== Panel 1: Valence Shell (MUST) + +Embedded Valence shell running inside a PanLL panel. Full reversible +filesystem ops, PTY allocation via Tauri shell plugin, Claude Code +integration, session recording (asciinema format), shared session mode +with approval gate. + +==== Panel 2: Game Preview (MUST) + +Live game preview via iframe/Tauri webview. Hot-reload, pause/resume, +frame-by-frame stepping, FPS counter, collision box overlay, gameplay +recording (WebM). + +==== Panel 3: VM Inspector (MUST) + +Visual debugger for the reversible VM. Stack visualisation, memory grid, +step forward/backward (reversible!), execution timeline scrubber, +breakpoints, subroutine call graph, multi-VM view for multiplayer. + +==== Panel 4: Network Topology (SHOULD) + +Force-directed graph of in-game network. Colour-coded zones, live packet +flow animation, defence flag badges, drag-to-rearrange for level design. + +==== Panel 5: Level Architect (SHOULD) + +Visual level design tool. Drag-and-drop device placement, guard patrol +path editor, defence flag toggles, level validation via VM simulation, +undo/redo with Valence checkpoints. + +==== Panel 6: Coprocessor Dashboard (SHOULD) + +Monitor 3 coprocessor backends (Compute, Security, I/O). Real-time call +log, health status, performance metrics, backend toggle. + +==== Panel 7: Multiplayer Monitor (COULD) + +WebSocket/Phoenix channel inspector. Lamport clock visualisation, device +lock status, latency graph, sync server process tree. + +==== Panel 8: DLC Workshop (COULD) + +Puzzle editor and test runner. VM instruction composer, difficulty +classification, asset bundling, puzzle chain editor. + +==== Panel 9-11: Editor Bridge, Build Dashboard, Release Manager + +Close-the-loop panels for LSP integration, CI/CD monitoring, and release +packaging. + +''''' + +=== Core eNSAID Features for IDApTIK + +==== TypeLL (Type-Level Intelligence) + +* Validate LevelConfig.res against expected schema +* Ensure all DeviceType variants handled +* Constraint propagation (guard count > 5 → alert threshold ≥ Medium) +* Temporal types: VM instruction sequences must be reversible (provable) + +==== ECHIDNA (Theorem Prover) + +[width="100%",cols="53%,47%",options="header",] +|=== +|Proof Obligation |What It Checks +|VM reversibility |`+undo(do(instruction, state)) == state+` for all 23 +instructions + +|Level solvability |At least one path from spawn to objective + +|Device reachability |All networked devices can reach gateway + +|Defence consistency |`+tamperProof+` and `+decoy+` are mutually +exclusive + +|Save/load roundtrip |`+deserialize(serialize(gameState)) == gameState+` + +|Coprocessor safety |Input ranges produce valid outputs (no NaN, no +overflow) +|=== + +==== Agentic Features (BoJ Cartridges) + +[cols=",",options="header",] +|=== +|Cartridge |IDApTIK Use +|`+database-mcp+` |Save/load game state to VeriSimDB +|`+git-mcp+` |Version control from within PanLL +|`+container-mcp+` |Build and deploy game containers +|`+observe-mcp+` |Game telemetry and performance monitoring +|`+nesy-mcp+` |Neurosymbolic reasoning for level design +|`+agent-mcp+` |Automated playtest workflows +|`+proof-mcp+` |ECHIDNA proof submission from BoJ +|=== + +''''' + +=== Collaborative Features (Parent-Child) + +==== Shared Session Mode + +* Both users see the same PanLL instance +* Valence Shell has "`approval gate`": child types command, parent +approves +* Game Preview shows both players in multiplayer mode +* VM Inspector supports "`explain mode`": step-by-step with annotations + +==== Recording and Sharing + +* Terminal sessions (asciinema .cast) +* Gameplay clips (WebM) +* Screenshots (any panel → Capture → PNG) +* Session bundles (ZIP export) + +''''' + +=== Recommended Panel Arrangement: IDApTIK Dev Mode + +.... +┌─────────────────────────────────────────────────────────────┐ +│ Panel Bar (vertical, left) │ +│ ┌──────────┬──────────────────────┬───────────────────────┐ │ +│ │ Panel-L │ Panel-N │ Panel-W │ │ +│ │ Level │ ECHIDNA │ Game Preview │ │ +│ │ Rules │ VM Proofs │ (live iframe) │ │ +│ │ │ │ │ │ +│ │ Device │ AI Commentary │ ┌─────────────┐ │ │ +│ │ Flags │ │ │ Network │ │ │ +│ │ │ Trust Level: │ │ Topology │ │ │ +│ │ Network │ ████ L3 │ │ Overlay │ │ │ +│ │ Constr. │ │ └─────────────┘ │ │ +│ ├──────────┴──────────────────────┴───────────────────────┤ │ +│ │ Valence Shell (bottom dock) │ │ +│ │ $ deno task dev │ │ +│ │ $ claude "help me add a new device type" │ │ +│ │ [Recording ●] [Share] [Screenshot] [Approval Gate: ON] │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ Status Bar: IDApTIK v0.1.0 | ReScript 12.1.0 | 0 errors │ +└─────────────────────────────────────────────────────────────┘ +.... + +''''' + +=== MuSCoCA Classification Summary + +==== MUST (6 items) + +Valence Shell, Game Preview, VM Inspector, Watcher integration, Panel +registration, TEA wiring + +==== SHOULD (7 items) + +Network Topology, Level Architect, Coprocessor Dashboard, Shared session +mode, ECHIDNA proofs, BoJ cartridges, Gameplay recording + +==== COULD (7 items) + +Multiplayer Monitor, DLC Workshop, Level difficulty estimator, +Coprocessor anomaly detection, VM execution timeline, Asset browser, +Session bundle export + +==== Corrective (4 items) + +Watcher debounce tuning, Panel-N OODA cycle, Capture format expansion, +Anti-Crash for game events + +==== Adaptive (4 items) + +ReScript 13 migration, Multi-VM networking, VeriSimDB temporal mode, +Tauri 2 mobile + +==== Perfective (6 items) + +Panel transitions, Keyboard shortcuts, Dark Start theme, Accessibility, +Performance, Panel presets + +''''' + +=== Implementation Phases + +==== Phase 1: Shell First (Week 1-2) + +Valence Shell panel + PTY + Claude Code + session recording + +==== Phase 2: Game Preview (Week 2-3) + +Embedded Vite dev server + hot-reload + FPS overlay + +==== Phase 3: VM Inspector (Week 3-4) + +VM state bridge + stack/memory visualisation + step forward/backward + +==== Phase 4: Network + Level Tools (Week 5-6) + +Network Topology + Level Architect + LevelConfig.res integration + +==== Phase 5: Collaborative Features (Week 7-8) + +Shared session mode + approval gate + recording + workspace preset + +''''' + +_Source files: `+panll/docs/DESIGN-DECISIONS.md+` and +`+panll/docs/DESIGN-2026-03-08-idaptik-ensaid.md+`_ diff --git a/docs/decisions/PANLL-ENSAID-SPEC-AND-DESIGN-DECISIONS.md b/docs/decisions/PANLL-ENSAID-SPEC-AND-DESIGN-DECISIONS.md deleted file mode 100644 index ce11fbf0..00000000 --- a/docs/decisions/PANLL-ENSAID-SPEC-AND-DESIGN-DECISIONS.md +++ /dev/null @@ -1,452 +0,0 @@ -# PanLL eNSAID Specification & Design Decisions -**Compiled: 2026-03-14** -**Source: panll/docs/DESIGN-DECISIONS.md + panll/docs/DESIGN-2026-03-08-idaptik-ensaid.md** - ---- - -# PART 1: eNSAID DESIGN DECISIONS (DD-001 to DD-018) - - - -**Last updated: 2026-03-02** -**Living document — updated as decisions are made or revised** - -## DD-001: eNSAID Is a Specification, PanLL Is an Implementation - -**Date:** 2026-02-27 -**Status:** Accepted -**Context:** Need to separate the idea from the tool so others can build competing implementations. - -**Decision:** eNSAID (Environment for NeSy-Agentic Integrated Development) is a specification. PanLL is the reference implementation. The spec lives in its own repo with its own governance. PanLL claims `IMPLEMENTS eNSAID` and that claim is verifiable. - -**Consequences:** -- Contributors contribute to the eNSAID ecosystem, not just PanLL -- Every panel written works with any compliant eNSAID environment -- Pattern: HTTP → Apache/Nginx/Caddy. SQL → Postgres/MySQL. LSP → every language server. -- If someone builds a better eNSAID, the idea survives - -**The V for Vendetta Principle:** You can kill PanLL. You cannot kill the idea. Ideas are bulletproof. - ---- - -## DD-002: Binary Star Architecture (Human-Machine Co-Orbit) - -**Date:** 2026-01-15 -**Status:** Accepted -**Context:** Traditional IDEs treat AI as subordinate tool. Need genuine co-working. - -**Decision:** Model Human and Machine as Binary Star system — two gravitationally bound entities orbiting a shared Barycentre (the task). Three panels: Panel-L (Symbolic/Human constraints), Panel-N (Neural/Machine reasoning), Panel-W (World/Barycentre results). Neither Human nor Machine is primary. - -**Consequences:** -- Operator sees Machine reasoning in real-time (Panel-N) -- Machine constrained by symbolic rules visible to both (Panel-L) -- Shared output space validates mutual understanding (Panel-W) -- Higher cognitive load initially, offset by Vexometer monitoring - ---- - -## DD-003: The Elm Architecture (TEA) for State Management - -**Date:** 2026-01-20 -**Status:** Accepted -**Context:** Complex UI with 14 panels, cognitive governance, orbital tracking needs deterministic state. - -**Decision:** Model-Update-View with Commands and Subscriptions. Single immutable model record. All state changes flow through typed messages. Custom TEA implementation extended for PanLL's needs. - -**Technical detail:** The main `model` type composes all domain slices via `include` re-exports. Each panel has its own Model/Engine/Cmd/Component files following a proven 8-file pattern. - ---- - -## DD-004: Panel Module Pattern (8 Files Per Panel) - -**Date:** 2026-03-01 -**Status:** Accepted -**Context:** Need a repeatable, consistent pattern for adding panels. - -**Decision:** Every panel follows exactly 8 files: - -| Layer | ReScript | Rust (if backend needed) | -|-------|----------|--------------------------| -| Types | `src/model/XModel.res` | `src-tauri/src/x/types.rs` | -| Engine | `src/core/XEngine.res` | — | -| Commands | `src/commands/XCmd.res` | `src-tauri/src/x/commands.rs` | -| Component | `src/components/X.res` | `src-tauri/src/x/mod.rs` | - -Plus wiring into 5 global files: Msg.res, Model.res, Update.res, View.res, main.rs - -**Consequences:** -- Panel Minter can generate this structure automatically -- Every panel is structurally identical — contributors know where everything is -- Engine files are pure functions (no side effects) — fully testable -- Cmd files handle Tauri IPC — all effects isolated - ---- - -## DD-005: Three-Tier Panel Isolation (Native / Standard Pod / Hardened Pod) - -**Date:** 2026-03-02 -**Status:** Accepted - -| Tier | Runtime | Security | Performance | Use Case | -|------|---------|----------|-------------|----------| -| **Native** | In-process (Tauri webview) | Full trust, hash-verified | Fastest | Core 14 panels | -| **Standard Pod** | Alpine + Podman container | Process isolation, network limited | Moderate overhead | Community panels, trusted | -| **Hardened Pod** | Stapeln + Chainguard image | Full Stapeln security stack, minimal attack surface | Higher overhead | Untrusted/experimental panels | - ---- - -## DD-006: Qubes-Style Code Provenance Map - -**Date:** 2026-03-02 -**Status:** Accepted - -Always-visible ambient trust surface (not a toggle). Parses git blame + Co-Authored-By headers. - -| Level | Colour | Meaning | -|-------|--------|---------| -| Verified | Green | Formally verified, proof-checked, no believe_me | -| Human-Reviewed | Blue | Human author or human commit after AI | -| AI-Assisted | Amber | Co-authored, no subsequent human review | -| Unreviewed AI | Red | Pure AI, no human in chain | -| Unknown | Grey | Pre-git or no attribution | - -**Hostile UX:** Unreviewed AI code gets pulsing red borders and increased visual friction. Users CAN suppress this, but the suppression action is itself visible ("pulled the smoke alarm battery"). - ---- - -## DD-007: Cognitive Governance Stack - -**Date:** 2026-01-25 -**Status:** Accepted - -Four interconnected governance systems: - -1. **Anti-Crash Gate** — Circuit breaker between Panel-N output and Panel-W workspace. Every neural token validated against Panel-L constraints before reaching shared space. -2. **Vexometer** — Friction monitor tracking cancellations, corrections, dwell time. Index 0.0–1.0 triggers anti-inflammatory UI adjustments. -3. **Information Humidity** — UI density adapts to stress. High humidity (relaxed) = more detail. Low humidity (stressed) = essential info only. -4. **Orbital Drift Aura** — Ambient visual (background colour shift) indicating system stability. - -These feed each other: Feedback-O-Tron → Vexometer → Humidity → UI adaptation. - ---- - -## DD-008: Accessibility as Core, Not Afterthought - -**Date:** 2026-02-27 -**Status:** Accepted - -Accessibility is in the CORE infrastructure: -- Panel Minter produces accessible panels by default (harder to make inaccessible than accessible) -- Every colour system ships with 4 accessibility palettes -- Every keyboard interaction works without a mouse -- Screen reader semantics (ARIA) in every component template -- Renamed broader concept to "information/cognitive ergonomics" - ---- - -## DD-009: Trust & Blame Separation - -**Date:** 2026-02-27 -**Status:** Accepted - -Two-tier trust model: - -1. **PanLL Core is hash-locked** — TEA framework, Tea_Vdom, Tea_Html, panel switcher, HAR are content-hashed. If core hashes don't match: `CORE_HASH_MISMATCH`, instantly detectable. -2. **Panels are author-signed** — Each panel manifest: `author: , signed: `. PanLL doesn't approve third-party panels, just hosts them. Blame is cryptographically attributable. - ---- - -## DD-010: Panel Taxonomy (Cladistic Classification) - -**Date:** 2026-03-02 -**Status:** Accepted - -Linnaean/cladistic hierarchy with EMPTY BRANCHES visible: - -| Level | Example | -|-------|---------| -| Kingdom | Development, Operations, Governance, Analysis | -| Phylum | Security, Languages, Databases, Infrastructure | -| Class | Static Analysis, Runtime Monitoring, Formal Verification | -| Order | Vulnerability Scanning, Compliance, Dependency Audit | -| Family | Web Security, Network Security, Supply Chain | -| Genus | Cloudflare Management, WordPress Hardening | -| Species | CloudGuard, Wharf | - -Empty nodes are specification slots, not stubs. Contributors see gaps and naturally fill them. - ---- - -## DD-011: Notepad++ Community as First Target - -**Date:** 2026-03-02 -**Status:** Accepted - -Target the Notepad++ community first. Metaphor: PanLL doesn't replace Notepad++ — it wraps around it. "The bionic Notepad++ user in a mech suit." - ---- - -## DD-012: Feedback-O-Tron as Opinion Mining System - -**Date:** 2026-03-02 -**Status:** Proposed - -Three-tier system: -1. **Panel Pulse** — Opinion mining extracts structured sentiment from feedback -2. **Prioritisation engine** — Maps sentiment to panel development priority -3. **Reusable infrastructure** — Same system usable by any product, not just PanLL - ---- - -## DD-013: Triaxial Development Framework (TSDM) - -**Date:** 2026-03-02 -**Status:** Accepted - -**Axis 1 — Scope:** must (5), intend (3), like (1) -**Axis 2 — Maintenance:** corrective (5), adaptive (3), perfective (1) -**Axis 3 — Audit:** systems (5), compliance (3), effects (1) - -Combined score: must+corrective+systems = 15 (do immediately), like+perfective+effects = 3 (backlog). - ---- - -## DD-014: FOSS-First Funding Strategy - -**Date:** 2026-03-02 -**Status:** Accepted - -Everything is MPL-2.0. Funding buys acceleration, not access. "Is it really worth trying to compete with a crazy academic, or just give him the money?" - ---- - -## DD-015: ReScript Technical Patterns - -**Date:** 2026-03-02 -**Status:** Accepted (standing reference) - -Key patterns: -- `Tea_Cmd.call(callbacks => { ... callbacks.enqueue(tagger(result)) ... })` for Tauri commands -- `@module("@tauri-apps/api/core") external invoke` for Tauri bindings -- `input(attrs, list{})` — Tea_Html input takes 2 args, not 1 -- `Attrs.style("width", "50%")` — two args (key, value), not single string -- No emoji literals in ReScript -- `exception` and `constraint` are reserved — use `domainExc` and `rule` - ---- - -## DD-016: Code MRI — Mutual Recognition & Integrity - -**Date:** 2026-03-02 -**Status:** Accepted - -Four-layer system: - -**Layer 0 — VoiceTag (Input):** Interactive annotation on code regions. Voice-activated (Web Speech API) but also keyboard/mouse. Tags numbered per file. - -**Layer 1 — Blake3 Provenance Chain:** Every code region gets a Blake3 hash covering content + author + timestamp + parent hash. Strip attribution? Hash mismatch — instantly detectable. Turnitin model flipped: collaborative attribution, not adversarial plagiarism detection. - -**Layer 2 — VeriSimDB Development Timeline:** Development-as-time-series database. Scrub a timeline slider to see the project state at any point — like the end credits of a worldbuilder documentary. - -**Layer 3 — Pattern Diagnostics & Gamification:** Derive development patterns from timeline data. Victory conditions: all TODOs resolved, zero panic-attack findings, Vexometer below threshold. - -**Layer 4 — Attribution-to-Licensing Link:** Blake3 provenance chains auto-generate license attribution sections. - ---- - -## DD-017: Care-On / Eco-Mode Tags and Adaptive Constraint Sensitivity - -**Date:** 2026-03-02 -**Status:** Accepted - -Tag modes: -- `care-on` — Extra scrutiny. Raises panic-attack sensitivity. -- `eco-mode` — Flags excessive allocation, energy-intensive loops. -- `burden` — "I know this is a problem but the fix requires a serious rewrite." - -Integrates with triaxial framework: eco-mode bumps to max priority, burden lowers audit axis. - ---- - -## DD-018: Dogfood Mode — Self-Hosting Policy Engine - -**Date:** 2026-03-02 -**Status:** Accepted - -Dogfood management with CRG-grade-driven policy: -- Grade D+ (Alpha): **Suggest** -- Grade E (Minimal): **Warn** -- Grade X/F (Untested/Harmful): **Ban** -- **Insist**: configurable per tool (no override) - ---- - ---- - -# PART 2: PanLL as eNSAID for IDApTIK Development - -**Date**: 2026-03-08 -**Author**: Jonathan D.A. Jewell -**Status**: Design (MuSCoCA-classified) - -## Overview - -This document designs PanLL as an **eNSAID** (Environment for NeSy-Agentic Integrated Development) tailored for IDApTIK game development — a collaborative parent-child workbench where Jonathan and his son can build, test, debug, visualise, and evolve the IDApixiTIK game together. - -The key insight: IDApTIK is a **reversible-computation stealth puzzle game** with a VM, multiplayer sync server, coprocessor system, device network topology, and formal verification layer. PanLL's three-panel neurosymbolic model maps directly onto this: - -| PanLL Panel | IDApTIK Mapping | -|-------------|-----------------| -| **Panel-L** (Symbolic) | VM instruction constraints, level rules, device defence flags, protocol specs | -| **Panel-N** (Neural) | ECHIDNA proof advisor for VM correctness, AI-assisted level design, NeSy reasoning | -| **Panel-W** (World) | Game preview, network topology view, device dashboard, telemetry | - ---- - -## The IDApTIK Panel Suite (11 panels) - -### Panel 1: Valence Shell (MUST) -Embedded Valence shell running inside a PanLL panel. Full reversible filesystem ops, PTY allocation via Tauri shell plugin, Claude Code integration, session recording (asciinema format), shared session mode with approval gate. - -### Panel 2: Game Preview (MUST) -Live game preview via iframe/Tauri webview. Hot-reload, pause/resume, frame-by-frame stepping, FPS counter, collision box overlay, gameplay recording (WebM). - -### Panel 3: VM Inspector (MUST) -Visual debugger for the reversible VM. Stack visualisation, memory grid, step forward/backward (reversible!), execution timeline scrubber, breakpoints, subroutine call graph, multi-VM view for multiplayer. - -### Panel 4: Network Topology (SHOULD) -Force-directed graph of in-game network. Colour-coded zones, live packet flow animation, defence flag badges, drag-to-rearrange for level design. - -### Panel 5: Level Architect (SHOULD) -Visual level design tool. Drag-and-drop device placement, guard patrol path editor, defence flag toggles, level validation via VM simulation, undo/redo with Valence checkpoints. - -### Panel 6: Coprocessor Dashboard (SHOULD) -Monitor 3 coprocessor backends (Compute, Security, I/O). Real-time call log, health status, performance metrics, backend toggle. - -### Panel 7: Multiplayer Monitor (COULD) -WebSocket/Phoenix channel inspector. Lamport clock visualisation, device lock status, latency graph, sync server process tree. - -### Panel 8: DLC Workshop (COULD) -Puzzle editor and test runner. VM instruction composer, difficulty classification, asset bundling, puzzle chain editor. - -### Panel 9-11: Editor Bridge, Build Dashboard, Release Manager -Close-the-loop panels for LSP integration, CI/CD monitoring, and release packaging. - ---- - -## Core eNSAID Features for IDApTIK - -### TypeLL (Type-Level Intelligence) -- Validate LevelConfig.res against expected schema -- Ensure all DeviceType variants handled -- Constraint propagation (guard count > 5 → alert threshold ≥ Medium) -- Temporal types: VM instruction sequences must be reversible (provable) - -### ECHIDNA (Theorem Prover) -| Proof Obligation | What It Checks | -|------------------|----------------| -| VM reversibility | `undo(do(instruction, state)) == state` for all 23 instructions | -| Level solvability | At least one path from spawn to objective | -| Device reachability | All networked devices can reach gateway | -| Defence consistency | `tamperProof` and `decoy` are mutually exclusive | -| Save/load roundtrip | `deserialize(serialize(gameState)) == gameState` | -| Coprocessor safety | Input ranges produce valid outputs (no NaN, no overflow) | - -### Agentic Features (BoJ Cartridges) -| Cartridge | IDApTIK Use | -|-----------|-------------| -| `database-mcp` | Save/load game state to VeriSimDB | -| `git-mcp` | Version control from within PanLL | -| `container-mcp` | Build and deploy game containers | -| `observe-mcp` | Game telemetry and performance monitoring | -| `nesy-mcp` | Neurosymbolic reasoning for level design | -| `agent-mcp` | Automated playtest workflows | -| `proof-mcp` | ECHIDNA proof submission from BoJ | - ---- - -## Collaborative Features (Parent-Child) - -### Shared Session Mode -- Both users see the same PanLL instance -- Valence Shell has "approval gate": child types command, parent approves -- Game Preview shows both players in multiplayer mode -- VM Inspector supports "explain mode": step-by-step with annotations - -### Recording and Sharing -- Terminal sessions (asciinema .cast) -- Gameplay clips (WebM) -- Screenshots (any panel → Capture → PNG) -- Session bundles (ZIP export) - ---- - -## Recommended Panel Arrangement: IDApTIK Dev Mode - -``` -┌─────────────────────────────────────────────────────────────┐ -│ Panel Bar (vertical, left) │ -│ ┌──────────┬──────────────────────┬───────────────────────┐ │ -│ │ Panel-L │ Panel-N │ Panel-W │ │ -│ │ Level │ ECHIDNA │ Game Preview │ │ -│ │ Rules │ VM Proofs │ (live iframe) │ │ -│ │ │ │ │ │ -│ │ Device │ AI Commentary │ ┌─────────────┐ │ │ -│ │ Flags │ │ │ Network │ │ │ -│ │ │ Trust Level: │ │ Topology │ │ │ -│ │ Network │ ████ L3 │ │ Overlay │ │ │ -│ │ Constr. │ │ └─────────────┘ │ │ -│ ├──────────┴──────────────────────┴───────────────────────┤ │ -│ │ Valence Shell (bottom dock) │ │ -│ │ $ deno task dev │ │ -│ │ $ claude "help me add a new device type" │ │ -│ │ [Recording ●] [Share] [Screenshot] [Approval Gate: ON] │ │ -│ └─────────────────────────────────────────────────────────┘ │ -│ Status Bar: IDApTIK v0.1.0 | ReScript 12.1.0 | 0 errors │ -└─────────────────────────────────────────────────────────────┘ -``` - ---- - -## MuSCoCA Classification Summary - -### MUST (6 items) -Valence Shell, Game Preview, VM Inspector, Watcher integration, Panel registration, TEA wiring - -### SHOULD (7 items) -Network Topology, Level Architect, Coprocessor Dashboard, Shared session mode, ECHIDNA proofs, BoJ cartridges, Gameplay recording - -### COULD (7 items) -Multiplayer Monitor, DLC Workshop, Level difficulty estimator, Coprocessor anomaly detection, VM execution timeline, Asset browser, Session bundle export - -### Corrective (4 items) -Watcher debounce tuning, Panel-N OODA cycle, Capture format expansion, Anti-Crash for game events - -### Adaptive (4 items) -ReScript 13 migration, Multi-VM networking, VeriSimDB temporal mode, Tauri 2 mobile - -### Perfective (6 items) -Panel transitions, Keyboard shortcuts, Dark Start theme, Accessibility, Performance, Panel presets - ---- - -## Implementation Phases - -### Phase 1: Shell First (Week 1-2) -Valence Shell panel + PTY + Claude Code + session recording - -### Phase 2: Game Preview (Week 2-3) -Embedded Vite dev server + hot-reload + FPS overlay - -### Phase 3: VM Inspector (Week 3-4) -VM state bridge + stack/memory visualisation + step forward/backward - -### Phase 4: Network + Level Tools (Week 5-6) -Network Topology + Level Architect + LevelConfig.res integration - -### Phase 5: Collaborative Features (Week 7-8) -Shared session mode + approval gate + recording + workspace preset - ---- - -*Source files: `panll/docs/DESIGN-DECISIONS.md` and `panll/docs/DESIGN-2026-03-08-idaptik-ensaid.md`* diff --git a/docs/design/DESIGN-2026-02-28-collaboration.adoc b/docs/design/DESIGN-2026-02-28-collaboration.adoc new file mode 100644 index 00000000..0300a6c5 --- /dev/null +++ b/docs/design/DESIGN-2026-02-28-collaboration.adoc @@ -0,0 +1,380 @@ +== DESIGN: PanLL Embedded Collaboration — Working Tools, Not a Meeting Platform + +*Date:* 2026-02-28 *Repo:* panll *Author:* Jonathan D.A. Jewell +*Status:* Design exploration (pre-implementation) + +=== Context + +PanLL’s proof, database, and protocol workflows are inherently +collaborative. A proof is often co-authored. A database schema is +negotiated between teams. A protocol spec needs consensus. But the +collaboration tools people reach for (Teams, Zoom, Slack) are +disconnected from the work — you share a screen and talk _about_ the +proof, but you can’t both _work on_ it simultaneously. + +This document designs embedded collaboration for PanLL: voice, chat, +shared cursors, and co-editing that live inside the tool where the work +happens. + +=== Design Questions (from session dialogue) + +____ +"`We also do need to have a feature a bit like VS Code’s Live Share +thing for teams wanting to collaborate together, as these are often +collaborative projects. Can our Elixir foundation support this too?`" +____ + +____ +"`I think with voice and/or chat, maybe video but that might be too +performance demanding, and other basic features that MS Teams offers — +but clearly this is not MS Teams, just working tools for doing this kind +of business.`" +____ + +''''' + +=== Core Principle: Work-First, Communication-Second + +This is *not* a videoconferencing platform that happens to show code. It +is a *proof/database/protocol workbench* that happens to let you talk to +colleagues while using it. The difference matters: + +[width="100%",cols="44%,56%",options="header",] +|=== +|MS Teams / Zoom |PanLL Collaboration +|Screen sharing (passive viewing) |Shared state (active co-editing) + +|"`Can you scroll up?`" |Both users see the same proof pipeline + +|Chat is a separate window |Chat is contextual — attached to goals, +entities, states + +|Video is the main event |Voice is ambient background; video is optional + +|General-purpose meetings |Purpose-built for formal methods / data / +protocol work + +|Disconnected from the artifact |Embedded in the artifact +|=== + +''''' + +=== Feature Set + +==== Tier 1: Shared State (Core — built on Phoenix Channels) + +The foundation. Multiple PanLL instances connect to the same session and +see synchronised state in real time. + +*What’s shared:* - Proof session state (goals, tactics applied, proof +script) - Pane layout and scroll position - Entity selections in +VeriSimDB - Protocol state machine edits - Cursor positions (coloured +per participant) - Tactic suggestions (everyone sees the same ECHIDNA +output) + +*What’s NOT shared (private to each participant):* - Personal layout +preferences - Information Humidity setting (one person may want Low +while another wants High) - Local SLM explanations - Undo history (each +user has their own undo stack) + +*Architecture:* + +.... +┌──────────┐ WebSocket ┌───────────────────┐ +│ PanLL A │◀──────────────────▶│ │ +└──────────┘ │ Elixir/Phoenix │ + │ Collaboration │ +┌──────────┐ WebSocket │ Server │ +│ PanLL B │◀──────────────────▶│ │ +└──────────┘ │ • Session state │ + │ • Presence │ +┌──────────┐ WebSocket │ • Conflict res. │ +│ PanLL C │◀──────────────────▶│ • Chat history │ +└──────────┘ │ • Voice relay │ + └────────┬──────────┘ + │ + ┌────▼────┐ + │ ECHIDNA │ + └─────────┘ +.... + +The collaboration server mediates between PanLL instances and ECHIDNA. +When participant A applies a tactic, the server forwards it to ECHIDNA, +receives the updated proof state, and broadcasts to all participants. No +one talks directly to ECHIDNA — the server is the single source of +truth. + +*Conflict resolution:* If two people apply a tactic at the same instant, +the server applies them sequentially (first-received wins) and +broadcasts the result. The second user sees their tactic applied to the +updated state, which may have different effects than they expected. The +UI shows a brief "`Alice applied '`induction n`' just before you`" +notification. + +==== Tier 2: Text Chat (Contextual) + +Chat messages can be: + +[arabic] +. *General:* Appears in a sidebar chat panel (like Slack/Teams DMs) +. *Contextual:* Attached to a specific proof goal, database entity, or +protocol state. Appears as a speech bubble annotation on the relevant +element. + +.... +┌──────────────────────────────────────────────────┐ +│ Goal: ∀ n, n + 0 = n │ +│ Status: 2 subgoals remaining │ +│ 💬 2 │◀── "2 comments on this goal" +│ ┌──────────────────────────────────────┐ │ +│ │ Alice: Should we try omega here? │ │ +│ │ Bob: No, induction is cleaner for │ │ +│ │ the inductive step │ │ +│ └──────────────────────────────────────┘ │ +└──────────────────────────────────────────────────┘ +.... + +*Contextual chat* is the differentiator. In Teams you say "`look at line +47`" and hope everyone scrolls there. In PanLL, the comment _lives on_ +the goal — it’s always visible when that goal is visible, across +sessions. + +*Implementation:* Phoenix PubSub with per-topic channels. Each proof +goal, entity, or protocol state has a topic. Chat messages are persisted +(ETS for session lifetime, optional DETS/Mnesia for longer-term +persistence). + +==== Tier 3: Voice (Ambient, Low-Bandwidth) + +Voice should feel like sitting next to a colleague — always-on, +low-latency, no ceremony. Not a "`call`" you schedule; just a channel +you’re in while working. + +*Requirements:* - *Opus codec* — excellent quality at 16-32 kbps +(negligible bandwidth) - *Push-to-talk AND open-mic* — user choice, +sensible default is open-mic with voice activity detection (VAD) - +*Spatial audio (optional):* Participants positioned left/right based on +their cursor location in the proof — if Alice is working on subgoal A +(left side of pipeline) and Bob on subgoal B (right side), their voices +come from those directions. Subtle but powerful for awareness. - *No +video by default* — audio is cheap and sufficient for co-working. Video +is available but opt-in (see Tier 4). + +*Implementation options:* + +[width="100%",cols="46%,27%,27%",options="header",] +|=== +|Approach |Pros |Cons +|WebRTC peer-to-peer |No server relay, low latency |NAT traversal +complexity, doesn’t scale past ~6 peers + +|WebRTC via SFU (mediasoup/Janus) |Scales to many participants |Requires +media server infrastructure + +|Elixir-native (Membrane Framework) |Pure Elixir, integrates with +Phoenix |Less mature than WebRTC ecosystem + +|LiveKit (open source) |Production-grade, WebRTC-based SFU |External +dependency but well-maintained +|=== + +*Recommendation:* WebRTC peer-to-peer for small teams (2-4 people, which +is the common case for proof co-authoring). If PanLL collaboration grows +to larger groups, add LiveKit as an optional SFU backend. The Elixir +server handles signalling (ICE candidates, SDP exchange) via Phoenix +Channels — it doesn’t relay media itself. + +==== Tier 4: Video (Optional, Opt-In) + +Video is available but never mandatory. Useful for: - Teaching sessions +(instructor shows their face while walking through a proof) - Remote +pair programming on protocol specs - Presentations (someone +screen-shares their PanLL while others watch) + +*Performance considerations:* - Video encoding/decoding is +GPU-accelerated on modern hardware (VA-API on Linux, VideoToolbox on +macOS) - 720p at 30fps is ~1.5 Mbps — manageable on any broadband +connection - PanLL should detect available bandwidth and auto-adjust +quality - Video should NEVER compete with the proof engine for CPU — if +ECHIDNA is running a heavy proof, video quality degrades gracefully + +*Tauri integration:* Tauri 2.0 can host a WebRTC peer connection via the +webview. The Rust backend handles no media — it all goes through the web +layer. + +==== Tier 5: Awareness Features (Borrowed from Teams, Adapted for Work) + +[width="100%",cols="22%,38%,40%",options="header",] +|=== +|Feature |Teams Equivalent |PanLL Adaptation +|Presence |Green/yellow/red dot |"`Alice: working on subgoal 2`", "`Bob: +reviewing axiom report`" + +|Reactions |Emoji reactions |"`Alice agreed with this tactic`" (👍 on a +proof step) + +|Raise hand |Raise hand button |"`Bob wants to discuss this goal before +proceeding`" (blocks tactic application until resolved) + +|Status |Custom status |"`Focusing — please don’t apply tactics to my +subgoal`" + +|Notifications |Toast notifications |"`Proof complete! All goals +discharged.`" broadcast to all participants +|=== + +*What PanLL does NOT need from Teams:* - Calendar integration - File +sharing (the proof IS the shared artifact) - Channels/teams hierarchy (a +PanLL session is the unit of collaboration) - Bots and app integrations +- Email integration - Backgrounds and filters + +''''' + +=== Session Model + +A *collaborative session* is: + +.... +Session { + id: UUID, + name: "Proving nat_add_zero_r with Alice and Bob", + layout: LogicAndProofs, // Discipline preset + participants: [Alice, Bob, Carol], + echidna_session: "sess-abc-123", // Linked ECHIDNA proof session + chat_history: [...], + created_at: timestamp, + expires_at: timestamp | never, +} +.... + +*Joining a session:* 1. Host creates a session (generates a share link +or room code) 2. Participants open PanLL and enter the room code 3. +Phoenix Presence registers them; cursors appear; state syncs 4. Voice +channel auto-joins (muted by default, unmute when ready) + +*No accounts required* for joining — the collaboration server identifies +participants by a nickname + session token. For persistent teams, +optional authentication via existing identity providers. + +''''' + +=== Elixir/Phoenix Fitness Assessment + +Why Elixir is exceptionally well-suited for this: + +[width="100%",cols="41%,59%",options="header",] +|=== +|Requirement |Elixir/OTP Feature +|Real-time state sync |Phoenix Channels (WebSocket multiplexing) + +|Participant tracking |Phoenix Presence (CRDT-based, conflict-free) + +|Chat persistence |ETS (in-memory, session-scoped) / Mnesia (cross-node) + +|Voice signalling |Phoenix Channel for WebRTC ICE/SDP exchange + +|Fault tolerance |OTP Supervisors (session crashes don’t affect other +sessions) + +|Scalability |BEAM handles millions of lightweight processes + +|Hot code upgrades |OTP releases — upgrade server without dropping +connections + +|Low latency |Sub-millisecond message routing within the BEAM +|=== + +The collaboration server is a natural Elixir application. Each session +is a GenServer process. Each participant’s connection is a Channel. +Presence tracks who’s in each session. The supervision tree ensures that +if one session crashes, all others continue unaffected. + +*Estimated implementation:* A basic shared-state + chat collaboration +server in Phoenix is roughly 500-800 lines of Elixir. Voice signalling +adds ~200 lines. This is a weekend project for the core, not a +multi-month effort. + +''''' + +=== Privacy and Security + +* *End-to-end encryption* for voice/video (WebRTC’s SRTP provides this +by default) +* *Chat messages* encrypted in transit (WSS) and optionally at rest +* *No telemetry* on collaboration content — PanLL never phones home with +proof data +* *Self-hostable* — the collaboration server can run on the user’s own +infrastructure +* *Session expiry* — sessions auto-delete after configurable timeout +(default: 24h of inactivity) +* *No recording* unless explicitly enabled by all participants + +''''' + +=== Implementation Phases + +==== Phase A: Shared proof state (Phoenix Channels) + +* [ ] Elixir/Phoenix collaboration server scaffold +* [ ] Session creation and joining (room codes) +* [ ] Real-time proof state synchronisation +* [ ] Cursor presence (coloured indicators) +* [ ] Conflict resolution for concurrent tactic applications + +==== Phase B: Contextual chat + +* [ ] General chat sidebar +* [ ] Contextual comments attached to proof goals / entities / states +* [ ] Chat persistence (session-scoped) + +==== Phase C: Voice + +* [ ] WebRTC signalling via Phoenix Channel +* [ ] Peer-to-peer audio (Opus codec) +* [ ] Push-to-talk and open-mic with VAD +* [ ] Mute/unmute UI in PanLL status bar + +==== Phase D: Video (optional) + +* [ ] WebRTC video stream (720p default) +* [ ] Bandwidth-adaptive quality +* [ ] Picture-in-picture mode (small video overlay, doesn’t obscure +panes) + +==== Phase E: Awareness features + +* [ ] Rich presence ("`working on subgoal 2`") +* [ ] Tactic reactions (👍 on proof steps) +* [ ] "`Hold`" flag (block tactic application pending discussion) + +''''' + +=== Open Questions + +[arabic] +. *Should the collaboration server be a separate Elixir application or +integrated into a broader PanLL backend?* Separate is cleaner for +deployment but means another service to run. +. *Should collaborative sessions be persisted beyond their lifetime?* +"`Replay a proof session`" could be valuable for teaching — watch how +Alice and Bob arrived at the proof step by step. +. *What about async collaboration?* Not everyone is online at the same +time. Should PanLL support "`leave a comment on this goal, Alice will +see it when she opens the session tomorrow`"? +. *Does the collaboration server need its own ECHIDNA connection, or +does each PanLL client still talk to ECHIDNA directly?* Centralising +through the server gives better conflict resolution but adds latency. +. *Should voice/video be integrated via Tauri’s webview WebRTC, or via a +native Rust WebRTC library (webrtc-rs)?* Webview is simpler; native +gives more control over codec selection and performance. + +''''' + +=== References + +* Discipline layouts: `+DESIGN-2026-02-28-discipline-layouts.md+` +* Proof UX: `+DESIGN-2026-02-28-echidna-proof-ux.md+` +* Phoenix Channels: https://hexdocs.pm/phoenix/channels.html +* Phoenix Presence: https://hexdocs.pm/phoenix/Phoenix.Presence.html +* Membrane Framework (Elixir media): https://membrane.stream +* LiveKit: https://livekit.io diff --git a/docs/design/DESIGN-2026-02-28-collaboration.md b/docs/design/DESIGN-2026-02-28-collaboration.md deleted file mode 100644 index 28034c77..00000000 --- a/docs/design/DESIGN-2026-02-28-collaboration.md +++ /dev/null @@ -1,327 +0,0 @@ -# DESIGN: PanLL Embedded Collaboration — Working Tools, Not a Meeting Platform - -**Date:** 2026-02-28 -**Repo:** panll -**Author:** Jonathan D.A. Jewell -**Status:** Design exploration (pre-implementation) - -## Context - -PanLL's proof, database, and protocol workflows are inherently collaborative. A -proof is often co-authored. A database schema is negotiated between teams. A protocol -spec needs consensus. But the collaboration tools people reach for (Teams, Zoom, -Slack) are disconnected from the work — you share a screen and talk *about* the -proof, but you can't both *work on* it simultaneously. - -This document designs embedded collaboration for PanLL: voice, chat, shared cursors, -and co-editing that live inside the tool where the work happens. - -## Design Questions (from session dialogue) - -> "We also do need to have a feature a bit like VS Code's Live Share thing for teams -> wanting to collaborate together, as these are often collaborative projects. Can our -> Elixir foundation support this too?" - -> "I think with voice and/or chat, maybe video but that might be too performance -> demanding, and other basic features that MS Teams offers — but clearly this is not -> MS Teams, just working tools for doing this kind of business." - ---- - -## Core Principle: Work-First, Communication-Second - -This is **not** a videoconferencing platform that happens to show code. It is a -**proof/database/protocol workbench** that happens to let you talk to colleagues -while using it. The difference matters: - -| MS Teams / Zoom | PanLL Collaboration | -|----------------|---------------------| -| Screen sharing (passive viewing) | Shared state (active co-editing) | -| "Can you scroll up?" | Both users see the same proof pipeline | -| Chat is a separate window | Chat is contextual — attached to goals, entities, states | -| Video is the main event | Voice is ambient background; video is optional | -| General-purpose meetings | Purpose-built for formal methods / data / protocol work | -| Disconnected from the artifact | Embedded in the artifact | - ---- - -## Feature Set - -### Tier 1: Shared State (Core — built on Phoenix Channels) - -The foundation. Multiple PanLL instances connect to the same session and see -synchronised state in real time. - -**What's shared:** -- Proof session state (goals, tactics applied, proof script) -- Pane layout and scroll position -- Entity selections in VeriSimDB -- Protocol state machine edits -- Cursor positions (coloured per participant) -- Tactic suggestions (everyone sees the same ECHIDNA output) - -**What's NOT shared (private to each participant):** -- Personal layout preferences -- Information Humidity setting (one person may want Low while another wants High) -- Local SLM explanations -- Undo history (each user has their own undo stack) - -**Architecture:** -``` -┌──────────┐ WebSocket ┌───────────────────┐ -│ PanLL A │◀──────────────────▶│ │ -└──────────┘ │ Elixir/Phoenix │ - │ Collaboration │ -┌──────────┐ WebSocket │ Server │ -│ PanLL B │◀──────────────────▶│ │ -└──────────┘ │ • Session state │ - │ • Presence │ -┌──────────┐ WebSocket │ • Conflict res. │ -│ PanLL C │◀──────────────────▶│ • Chat history │ -└──────────┘ │ • Voice relay │ - └────────┬──────────┘ - │ - ┌────▼────┐ - │ ECHIDNA │ - └─────────┘ -``` - -The collaboration server mediates between PanLL instances and ECHIDNA. When -participant A applies a tactic, the server forwards it to ECHIDNA, receives the -updated proof state, and broadcasts to all participants. No one talks directly -to ECHIDNA — the server is the single source of truth. - -**Conflict resolution:** If two people apply a tactic at the same instant, the server -applies them sequentially (first-received wins) and broadcasts the result. The second -user sees their tactic applied to the updated state, which may have different effects -than they expected. The UI shows a brief "Alice applied 'induction n' just before -you" notification. - -### Tier 2: Text Chat (Contextual) - -Chat messages can be: - -1. **General:** Appears in a sidebar chat panel (like Slack/Teams DMs) -2. **Contextual:** Attached to a specific proof goal, database entity, or protocol - state. Appears as a speech bubble annotation on the relevant element. - -``` -┌──────────────────────────────────────────────────┐ -│ Goal: ∀ n, n + 0 = n │ -│ Status: 2 subgoals remaining │ -│ 💬 2 │◀── "2 comments on this goal" -│ ┌──────────────────────────────────────┐ │ -│ │ Alice: Should we try omega here? │ │ -│ │ Bob: No, induction is cleaner for │ │ -│ │ the inductive step │ │ -│ └──────────────────────────────────────┘ │ -└──────────────────────────────────────────────────┘ -``` - -**Contextual chat** is the differentiator. In Teams you say "look at line 47" and -hope everyone scrolls there. In PanLL, the comment *lives on* the goal — it's -always visible when that goal is visible, across sessions. - -**Implementation:** Phoenix PubSub with per-topic channels. Each proof goal, entity, -or protocol state has a topic. Chat messages are persisted (ETS for session lifetime, -optional DETS/Mnesia for longer-term persistence). - -### Tier 3: Voice (Ambient, Low-Bandwidth) - -Voice should feel like sitting next to a colleague — always-on, low-latency, no -ceremony. Not a "call" you schedule; just a channel you're in while working. - -**Requirements:** -- **Opus codec** — excellent quality at 16-32 kbps (negligible bandwidth) -- **Push-to-talk AND open-mic** — user choice, sensible default is open-mic with - voice activity detection (VAD) -- **Spatial audio (optional):** Participants positioned left/right based on their - cursor location in the proof — if Alice is working on subgoal A (left side of - pipeline) and Bob on subgoal B (right side), their voices come from those - directions. Subtle but powerful for awareness. -- **No video by default** — audio is cheap and sufficient for co-working. Video is - available but opt-in (see Tier 4). - -**Implementation options:** - -| Approach | Pros | Cons | -|----------|------|------| -| WebRTC peer-to-peer | No server relay, low latency | NAT traversal complexity, doesn't scale past ~6 peers | -| WebRTC via SFU (mediasoup/Janus) | Scales to many participants | Requires media server infrastructure | -| Elixir-native (Membrane Framework) | Pure Elixir, integrates with Phoenix | Less mature than WebRTC ecosystem | -| LiveKit (open source) | Production-grade, WebRTC-based SFU | External dependency but well-maintained | - -**Recommendation:** WebRTC peer-to-peer for small teams (2-4 people, which is the -common case for proof co-authoring). If PanLL collaboration grows to larger groups, -add LiveKit as an optional SFU backend. The Elixir server handles signalling (ICE -candidates, SDP exchange) via Phoenix Channels — it doesn't relay media itself. - -### Tier 4: Video (Optional, Opt-In) - -Video is available but never mandatory. Useful for: -- Teaching sessions (instructor shows their face while walking through a proof) -- Remote pair programming on protocol specs -- Presentations (someone screen-shares their PanLL while others watch) - -**Performance considerations:** -- Video encoding/decoding is GPU-accelerated on modern hardware (VA-API on Linux, - VideoToolbox on macOS) -- 720p at 30fps is ~1.5 Mbps — manageable on any broadband connection -- PanLL should detect available bandwidth and auto-adjust quality -- Video should NEVER compete with the proof engine for CPU — if ECHIDNA is running - a heavy proof, video quality degrades gracefully - -**Tauri integration:** Tauri 2.0 can host a WebRTC peer connection via the webview. -The Rust backend handles no media — it all goes through the web layer. - -### Tier 5: Awareness Features (Borrowed from Teams, Adapted for Work) - -| Feature | Teams Equivalent | PanLL Adaptation | -|---------|-----------------|------------------| -| Presence | Green/yellow/red dot | "Alice: working on subgoal 2", "Bob: reviewing axiom report" | -| Reactions | Emoji reactions | "Alice agreed with this tactic" (👍 on a proof step) | -| Raise hand | Raise hand button | "Bob wants to discuss this goal before proceeding" (blocks tactic application until resolved) | -| Status | Custom status | "Focusing — please don't apply tactics to my subgoal" | -| Notifications | Toast notifications | "Proof complete! All goals discharged." broadcast to all participants | - -**What PanLL does NOT need from Teams:** -- Calendar integration -- File sharing (the proof IS the shared artifact) -- Channels/teams hierarchy (a PanLL session is the unit of collaboration) -- Bots and app integrations -- Email integration -- Backgrounds and filters - ---- - -## Session Model - -A **collaborative session** is: - -``` -Session { - id: UUID, - name: "Proving nat_add_zero_r with Alice and Bob", - layout: LogicAndProofs, // Discipline preset - participants: [Alice, Bob, Carol], - echidna_session: "sess-abc-123", // Linked ECHIDNA proof session - chat_history: [...], - created_at: timestamp, - expires_at: timestamp | never, -} -``` - -**Joining a session:** -1. Host creates a session (generates a share link or room code) -2. Participants open PanLL and enter the room code -3. Phoenix Presence registers them; cursors appear; state syncs -4. Voice channel auto-joins (muted by default, unmute when ready) - -**No accounts required** for joining — the collaboration server identifies -participants by a nickname + session token. For persistent teams, optional -authentication via existing identity providers. - ---- - -## Elixir/Phoenix Fitness Assessment - -Why Elixir is exceptionally well-suited for this: - -| Requirement | Elixir/OTP Feature | -|-------------|-------------------| -| Real-time state sync | Phoenix Channels (WebSocket multiplexing) | -| Participant tracking | Phoenix Presence (CRDT-based, conflict-free) | -| Chat persistence | ETS (in-memory, session-scoped) / Mnesia (cross-node) | -| Voice signalling | Phoenix Channel for WebRTC ICE/SDP exchange | -| Fault tolerance | OTP Supervisors (session crashes don't affect other sessions) | -| Scalability | BEAM handles millions of lightweight processes | -| Hot code upgrades | OTP releases — upgrade server without dropping connections | -| Low latency | Sub-millisecond message routing within the BEAM | - -The collaboration server is a natural Elixir application. Each session is a GenServer -process. Each participant's connection is a Channel. Presence tracks who's in each -session. The supervision tree ensures that if one session crashes, all others continue -unaffected. - -**Estimated implementation:** A basic shared-state + chat collaboration server in -Phoenix is roughly 500-800 lines of Elixir. Voice signalling adds ~200 lines. This -is a weekend project for the core, not a multi-month effort. - ---- - -## Privacy and Security - -- **End-to-end encryption** for voice/video (WebRTC's SRTP provides this by default) -- **Chat messages** encrypted in transit (WSS) and optionally at rest -- **No telemetry** on collaboration content — PanLL never phones home with proof data -- **Self-hostable** — the collaboration server can run on the user's own infrastructure -- **Session expiry** — sessions auto-delete after configurable timeout (default: 24h - of inactivity) -- **No recording** unless explicitly enabled by all participants - ---- - -## Implementation Phases - -### Phase A: Shared proof state (Phoenix Channels) -- [ ] Elixir/Phoenix collaboration server scaffold -- [ ] Session creation and joining (room codes) -- [ ] Real-time proof state synchronisation -- [ ] Cursor presence (coloured indicators) -- [ ] Conflict resolution for concurrent tactic applications - -### Phase B: Contextual chat -- [ ] General chat sidebar -- [ ] Contextual comments attached to proof goals / entities / states -- [ ] Chat persistence (session-scoped) - -### Phase C: Voice -- [ ] WebRTC signalling via Phoenix Channel -- [ ] Peer-to-peer audio (Opus codec) -- [ ] Push-to-talk and open-mic with VAD -- [ ] Mute/unmute UI in PanLL status bar - -### Phase D: Video (optional) -- [ ] WebRTC video stream (720p default) -- [ ] Bandwidth-adaptive quality -- [ ] Picture-in-picture mode (small video overlay, doesn't obscure panes) - -### Phase E: Awareness features -- [ ] Rich presence ("working on subgoal 2") -- [ ] Tactic reactions (👍 on proof steps) -- [ ] "Hold" flag (block tactic application pending discussion) - ---- - -## Open Questions - -1. **Should the collaboration server be a separate Elixir application or integrated - into a broader PanLL backend?** Separate is cleaner for deployment but means - another service to run. - -2. **Should collaborative sessions be persisted beyond their lifetime?** "Replay a - proof session" could be valuable for teaching — watch how Alice and Bob arrived - at the proof step by step. - -3. **What about async collaboration?** Not everyone is online at the same time. - Should PanLL support "leave a comment on this goal, Alice will see it when she - opens the session tomorrow"? - -4. **Does the collaboration server need its own ECHIDNA connection, or does each - PanLL client still talk to ECHIDNA directly?** Centralising through the server - gives better conflict resolution but adds latency. - -5. **Should voice/video be integrated via Tauri's webview WebRTC, or via a native - Rust WebRTC library (webrtc-rs)?** Webview is simpler; native gives more control - over codec selection and performance. - ---- - -## References - -- Discipline layouts: `DESIGN-2026-02-28-discipline-layouts.md` -- Proof UX: `DESIGN-2026-02-28-echidna-proof-ux.md` -- Phoenix Channels: https://hexdocs.pm/phoenix/channels.html -- Phoenix Presence: https://hexdocs.pm/phoenix/Phoenix.Presence.html -- Membrane Framework (Elixir media): https://membrane.stream -- LiveKit: https://livekit.io diff --git a/docs/design/DESIGN-2026-02-28-discipline-layouts.adoc b/docs/design/DESIGN-2026-02-28-discipline-layouts.adoc new file mode 100644 index 00000000..a83afd42 --- /dev/null +++ b/docs/design/DESIGN-2026-02-28-discipline-layouts.adoc @@ -0,0 +1,387 @@ +== DESIGN: PanLL Discipline Layouts — Viewshift Presets for Domain-Specific Workflows + +*Date:* 2026-02-28 *Repo:* panll *Author:* Jonathan D.A. Jewell +*Status:* Design exploration (pre-implementation) + +=== Context + +PanLL’s three-pane model (Pane-L symbolic, Pane-N neural, Pane-W world) +is domain-agnostic by design. But different disciplines need different +things _visible by default_. A database designer doesn’t need the full +proof pipeline front-and-centre; a protocol designer doesn’t need the +entity browser. Yet all of them benefit from the neural stream, the +topology view, and the ECHIDNA proof engine when they need it. + +This document proposes a *global viewshift* — a dropdown at the top of +the PanLL window that reconfigures which panes, sub-panels, and tools +are visible, sized, and prioritised for a given discipline. + +=== Design Questions (from session dialogue) + +____ +"`I wonder if there can be a global-viewshift thing at the top in which +the panel system can arrange into a default set of panes for e.g. logic +and proofs, an ideal set of panes for the database designer/developer, +the ideal set for the programming language designer/developer, and the +ideal set for the protocol designer/developer, custom sets if desired.`" +____ + +____ +"`Not everyone is a database person, or might know about how what is a +problem in protocol design if they have never worked in them.`" +____ + +____ +"`People offering additional layouts for this and/or extended features +as time goes on?`" +____ + +''''' + +=== Architecture: Layout Presets + +A *layout preset* is a named configuration that specifies: + +[arabic] +. *Which panes are visible* and their relative sizing +. *Which sub-panels are expanded* within each pane +. *Which ECHIDNA prover backends are prioritised* in the suggestion +engine +. *Which notation mode the syntax linter defaults to* +. *Which toolbar buttons are promoted* vs. hidden in overflow + +.... +┌──────────────────────────────────────────────────────────────┐ +│ PanLL eNSAID [▼ Layout: Logic & Proofs ▼] [≡] │ +├──────────────────────────────────────────────────────────────┤ +│ (panes reconfigure based on selection) │ +└──────────────────────────────────────────────────────────────┘ +.... + +The dropdown is always visible. Switching layouts is instant (no reload +— just re-arranging visibility/sizing of existing components). + +''''' + +=== Core Layouts + +==== 1. Logic & Proofs + +*Target audience:* Mathematicians, logicians, formal methods +researchers, students entering the border of maths and logic. + +*Key insight:* These users may be sophisticated in mathematics but +unfamiliar with tactic-based proof systems, types-as-propositions, or +specific prover syntax. The visual proof builder (from the companion +design doc) is front-and-centre. + +[cols=",,,",options="header",] +|=== +|Pane |Visible |Size |Primary Content +|Pane-L (Symbolic) |Yes |35% |Proof Pipeline (visual) +|Pane-N (Neural) |Yes |25% |Tactic suggestions, SLM +|Pane-W (World) |Yes |40% |Proof Script Editor +|ECHIDNA Panel |Expanded |— |Session controls, trust +|VeriSimDB Panel |Collapsed |— |Available if needed +|Security/Panic |Hidden |— |Not relevant +|=== + +*Pane-L details:* Visual proof builder, logical notation palette, +goal/hypothesis display. *Pane-N details:* Neural stream with tactic +suggestions, ECHIDNA advisor monologue, SLM explainer. *Pane-W details:* +Switchable syntax proof script editor, theorem search, library browser. +*ECHIDNA details:* Prover selector (Coq/Lean/Isabelle prioritised), +trust display. + +*Default prover priority:* Coq → Lean 4 → Isabelle → Agda → Z3 *Default +notation:* PanLL-Universal (with switch to Coq/Lean syntax) *Promoted +toolbar:* New Proof, Apply Tactic, Suggest, Undo Step, QED Check + +''''' + +==== 2. Database Design & Development + +*Target audience:* Database designers, data modellers, query developers, +people working with VeriSimDB/QuandleDB/LithoGlyph or other multi-modal +databases. + +*Key insight:* These users need entity browsers, drift detection, query +editors, and the ability to verify data integrity constraints. ECHIDNA +is available for proving query correctness or schema invariants but +isn’t the primary workflow. + +[cols=",,,",options="header",] +|=== +|Pane |Visible |Size |Primary Content +|Pane-L (Symbolic) |Yes |30% |Schema/constraint editor +|Pane-N (Neural) |Yes |20% |Drift alerts, suggestions +|Pane-W (World) |Yes |50% |Entity browser, query results +|VeriSimDB Panel |Expanded |— |Full database controls +|ECHIDNA Panel |Collapsed |— |Schema invariant proofs +|Security/Panic |Collapsed |— |Database stress-testing +|=== + +*Pane-L details:* VCL-DT query builder, type definitions, constraint +editing. *Pane-N details:* Neural stream, drift alerts, normalisation +suggestions. *Pane-W details:* Entity browser, query results, drift +heatmap, telemetry dashboard. *VeriSimDB details:* Connection, entities, +drift, normalisation, orchestrator status. + +*Default ECHIDNA use:* Proving data integrity constraints, schema +migration safety *Default notation:* VCL-DT (VeriSimDB Query Language +with Dependent Types) *Promoted toolbar:* Query, Browse Entities, Check +Drift, Normalise, Telemetry + +''''' + +==== 3. Programming Language Design & Development + +*Target audience:* Language designers, compiler writers, people building +or extending Eclexia, AffineScript, BetLang, or similar languages. + +*Key insight:* These users need to verify type system properties, prove +compiler transformations correct, test parser grammars, and browse ASTs. +The proof engine is heavily used but through a language-design lens +(metatheory, not end-user proofs). + +[cols=",,,",options="header",] +|=== +|Pane |Visible |Size |Primary Content +|Pane-L (Symbolic) |Yes |40% |Type rule editor, BNF viewer +|Pane-N (Neural) |Yes |25% |Inference trace, suggestions +|Pane-W (World) |Yes |35% |AST browser, test runner +|ECHIDNA Panel |Expanded |— |Metatheory proofs +|VeriSimDB Panel |Hidden |— |Not typically needed +|Security/Panic |Collapsed |— |Parser fuzzing +|=== + +*Pane-L details:* Type rule editor, grammar/BNF viewer, metatheory goal +display. *Pane-N details:* Neural stream, type inference trace, +compilation suggestions. *Pane-W details:* AST browser, test case +runner, example program editor. *ECHIDNA details:* Type safety, +progress, preservation proofs; Coq/Lean formalisation. + +*Default prover priority:* Coq → Lean 4 → Agda (metatheory-focused) +*Default notation:* Higher-order logic / dependent types *Promoted +toolbar:* Define Rule, Check Metatheory, Parse Example, Run Evaluator + +''''' + +==== 4. Protocol Design & Development + +*Target audience:* Network protocol designers, distributed systems +engineers, people working on Axel Protocol, TPCF, or similar +specifications. + +*Key insight:* These users need to verify protocol properties (liveness, +safety, deadlock freedom), model state machines, check message format +correctness, and reason about concurrency. Many may not come from a +formal methods background and need the protocol-specific vocabulary +(message flows, state transitions, invariants) rather than generic proof +terminology. + +[cols=",,,",options="header",] +|=== +|Pane |Visible |Size |Primary Content +|Pane-L (Symbolic) |Yes |35% |State machine editor +|Pane-N (Neural) |Yes |25% |Deadlock warnings, analysis +|Pane-W (World) |Yes |40% |Message flow diagram +|ECHIDNA Panel |Expanded |— |Model checking, liveness +|VeriSimDB Panel |Collapsed |— |Protocol trace storage +|Security/Panic |Expanded |— |Protocol fuzzing +|=== + +*Pane-L details:* State machine editor, protocol invariants, message +format specs. *Pane-N details:* Neural stream, protocol analysis +suggestions, deadlock warnings. *Pane-W details:* Message flow diagram, +simulation runner, test harness. *ECHIDNA details:* TLA+/Z3 model +checking, liveness/safety proofs. + +*Default prover priority:* Z3 → TLA+ (via ECHIDNA) → Spin → Isabelle +*Default notation:* Temporal logic (□ ◇ U), state predicates *Promoted +toolbar:* Define State, Add Transition, Check Liveness, Simulate, Fuzz + +''''' + +==== 5. General / Custom + +*Target audience:* Users whose workflow doesn’t fit neatly into the +above, or who want to build their own layout. + +This is the current PanLL default — all panes visible at equal sizing, +all sub-panels collapsed. Users can drag pane borders to resize, +expand/collapse any sub-panel, and save their arrangement as a named +custom layout. + +''''' + +=== Shared Core (Always Available Regardless of Layout) + +Every layout includes these foundational elements: + +[width="100%",cols="27%,25%,48%",options="header",] +|=== +|Element |Purpose |Always Visible? +|Neural Stream |ECHIDNA advisor + inference tokens |Yes (can be +minimised) + +|Topology View |Binary Star diagram |Yes (toggleable) + +|ECHIDNA Health |Connection indicator + version |Yes (status bar) + +|Anti-Crash |Validation layer |Yes (background) + +|Vexometer |Operator vexation tracking |Yes (status bar) + +|Orbital Sync |Cross-pane synchronisation |Yes (background) + +|Contractiles |Contract enforcement |Yes (background) + +|Keyboard shortcuts |Global hotkeys |Yes +|=== + +''''' + +=== Layout Extensibility + +==== User-Defined Layouts + +Users can: 1. Start from any preset 2. Rearrange panes (drag borders, +collapse/expand panels) 3. Save as named custom layout 4. Export/import +layout configs (JSON) + +==== Community Layouts + +Third parties can contribute layout presets as JSON files in a +`+layouts/+` directory. Each layout file specifies: + +[source,json] +---- +{ + "name": "Cryptographic Protocol Verification", + "description": "Optimised for verifying crypto protocol properties", + "author": "contributor-name", + "version": "1.0.0", + "base": "protocol", + "overrides": { + "echidna": { + "defaultProvers": ["z3", "tamarin"], + "defaultNotation": "applied-pi-calculus" + }, + "paneL": { + "defaultContent": "protocol-spec-editor", + "size": 40 + } + } +} +---- + +This follows the PanLL extensibility philosophy: the core ships with 4-5 +useful presets, but the system is open for community contribution +without requiring code changes. + +''''' + +=== Relationship to Progressive Sophistication + +The discipline layouts are *orthogonal* to the progressive +sophistication levels described in the companion design doc (Visual → +Syntax → Logic → REPL). Within any discipline layout, the user can still +operate at any sophistication level: + +* A *database designer* at Level 1 drags query blocks visually +* A *database designer* at Level 3 writes VCL-DT with logical notation +* A *protocol designer* at Level 1 draws state machines visually +* A *protocol designer* at Level 4 writes raw TLA+ in a REPL + +The layout controls _what_ is visible. The sophistication level controls +_how_ the user interacts with it. + +.... + Layout (WHAT) + ┌──────────────────────────┐ + │ Logic │ DB │ Lang │ Proto │ + ┌────────────┼──────┼────┼──────┼───────┤ + │ Visual │ A │ B │ C │ D │ + S │ Syntax │ E │ F │ G │ H │ + O │ Logic │ I │ J │ K │ L │ + P │ REPL │ M │ N │ O │ P │ + H └────────────┴──────┴────┴──────┴───────┘ + (HOW) + +Each cell (A-P) is a valid configuration. +.... + +''''' + +=== Implementation Notes + +==== Model Changes + +Add to `+Model.res+`: + +[source,rescript] +---- +/// Discipline layout presets for the global viewshift dropdown. +type disciplineLayout = + | LogicAndProofs + | DatabaseDesign + | LanguageDesign + | ProtocolDesign + | General + | Custom(string) // Named custom layout + +/// Layout configuration — which panes and sub-panels are visible and how +/// they are sized. This is the "recipe" that a disciplineLayout applies. +type layoutConfig = { + paneLSize: int, // Percentage width (0-100) + paneNSize: int, + paneWSize: int, + echidnaExpanded: bool, + verisimdbExpanded: bool, + securityExpanded: bool, + defaultProvers: array, + defaultNotation: string, + promotedActions: array, +} +---- + +==== Message Changes + +[source,rescript] +---- +| SwitchLayout(disciplineLayout) +| SaveCustomLayout(string) +| LoadCustomLayout(string) +---- + +==== Persistence + +Layout preference is stored in localStorage alongside existing PanLL +state. Custom layouts are stored as JSON in the user’s config directory. + +''''' + +=== Open Questions + +[arabic] +. *Should layouts also control the Information Humidity default?* E.g., +database designers might want Medium (show entity details) while +protocol designers might want Low (focus on state machine, shed noise). +. *Should the layout dropdown show a preview thumbnail?* A small +wireframe showing the pane arrangement before switching. +. *Can layouts be parameterised by project?* E.g., "`When I open the +VeriSimDB project, auto-switch to Database Design layout.`" +. *Should community layouts live in a PanLL registry or just be files?* +A registry allows discovery but adds infrastructure burden. + +''''' + +=== References + +* Companion design: `+DESIGN-2026-02-28-echidna-proof-ux.md+` +* ReScript Evangeliser view layers: +`+developer-ecosystem/rescript-ecosystem/packages/tooling/evangeliser/src/Types.res+` +* PanLL Model types: `+panll/src/Model.res+` +* PanLL three-pane architecture: +`+panll/docs/PANLL-COMPLETE-STATUS-2026-02-11.md+` diff --git a/docs/design/DESIGN-2026-02-28-discipline-layouts.md b/docs/design/DESIGN-2026-02-28-discipline-layouts.md deleted file mode 100644 index e1808b2b..00000000 --- a/docs/design/DESIGN-2026-02-28-discipline-layouts.md +++ /dev/null @@ -1,350 +0,0 @@ -# DESIGN: PanLL Discipline Layouts — Viewshift Presets for Domain-Specific Workflows - -**Date:** 2026-02-28 -**Repo:** panll -**Author:** Jonathan D.A. Jewell -**Status:** Design exploration (pre-implementation) - -## Context - -PanLL's three-pane model (Pane-L symbolic, Pane-N neural, Pane-W world) is -domain-agnostic by design. But different disciplines need different things *visible -by default*. A database designer doesn't need the full proof pipeline front-and-centre; -a protocol designer doesn't need the entity browser. Yet all of them benefit from -the neural stream, the topology view, and the ECHIDNA proof engine when they need it. - -This document proposes a **global viewshift** — a dropdown at the top of the PanLL -window that reconfigures which panes, sub-panels, and tools are visible, sized, and -prioritised for a given discipline. - -## Design Questions (from session dialogue) - -> "I wonder if there can be a global-viewshift thing at the top in which the panel -> system can arrange into a default set of panes for e.g. logic and proofs, an ideal -> set of panes for the database designer/developer, the ideal set for the programming -> language designer/developer, and the ideal set for the protocol designer/developer, -> custom sets if desired." - -> "Not everyone is a database person, or might know about how what is a problem in -> protocol design if they have never worked in them." - -> "People offering additional layouts for this and/or extended features as time goes on?" - ---- - -## Architecture: Layout Presets - -A **layout preset** is a named configuration that specifies: - -1. **Which panes are visible** and their relative sizing -2. **Which sub-panels are expanded** within each pane -3. **Which ECHIDNA prover backends are prioritised** in the suggestion engine -4. **Which notation mode the syntax linter defaults to** -5. **Which toolbar buttons are promoted** vs. hidden in overflow - -``` -┌──────────────────────────────────────────────────────────────┐ -│ PanLL eNSAID [▼ Layout: Logic & Proofs ▼] [≡] │ -├──────────────────────────────────────────────────────────────┤ -│ (panes reconfigure based on selection) │ -└──────────────────────────────────────────────────────────────┘ -``` - -The dropdown is always visible. Switching layouts is instant (no reload — just -re-arranging visibility/sizing of existing components). - ---- - -## Core Layouts - -### 1. Logic & Proofs - -**Target audience:** Mathematicians, logicians, formal methods researchers, students -entering the border of maths and logic. - -**Key insight:** These users may be sophisticated in mathematics but unfamiliar with -tactic-based proof systems, types-as-propositions, or specific prover syntax. The -visual proof builder (from the companion design doc) is front-and-centre. - -| Pane | Visible | Size | Primary Content | -|-------------------|-----------|------|------------------------------| -| Pane-L (Symbolic) | Yes | 35% | Proof Pipeline (visual) | -| Pane-N (Neural) | Yes | 25% | Tactic suggestions, SLM | -| Pane-W (World) | Yes | 40% | Proof Script Editor | -| ECHIDNA Panel | Expanded | — | Session controls, trust | -| VeriSimDB Panel | Collapsed | — | Available if needed | -| Security/Panic | Hidden | — | Not relevant | - -**Pane-L details:** Visual proof builder, logical notation palette, goal/hypothesis -display. -**Pane-N details:** Neural stream with tactic suggestions, ECHIDNA advisor monologue, -SLM explainer. -**Pane-W details:** Switchable syntax proof script editor, theorem search, library -browser. -**ECHIDNA details:** Prover selector (Coq/Lean/Isabelle prioritised), trust display. - -**Default prover priority:** Coq → Lean 4 → Isabelle → Agda → Z3 -**Default notation:** PanLL-Universal (with switch to Coq/Lean syntax) -**Promoted toolbar:** New Proof, Apply Tactic, Suggest, Undo Step, QED Check - ---- - -### 2. Database Design & Development - -**Target audience:** Database designers, data modellers, query developers, people -working with VeriSimDB/QuandleDB/LithoGlyph or other multi-modal databases. - -**Key insight:** These users need entity browsers, drift detection, query editors, -and the ability to verify data integrity constraints. ECHIDNA is available for -proving query correctness or schema invariants but isn't the primary workflow. - -| Pane | Visible | Size | Primary Content | -|-------------------|-----------|------|------------------------------| -| Pane-L (Symbolic) | Yes | 30% | Schema/constraint editor | -| Pane-N (Neural) | Yes | 20% | Drift alerts, suggestions | -| Pane-W (World) | Yes | 50% | Entity browser, query results| -| VeriSimDB Panel | Expanded | — | Full database controls | -| ECHIDNA Panel | Collapsed | — | Schema invariant proofs | -| Security/Panic | Collapsed | — | Database stress-testing | - -**Pane-L details:** VCL-DT query builder, type definitions, constraint editing. -**Pane-N details:** Neural stream, drift alerts, normalisation suggestions. -**Pane-W details:** Entity browser, query results, drift heatmap, telemetry dashboard. -**VeriSimDB details:** Connection, entities, drift, normalisation, orchestrator status. - -**Default ECHIDNA use:** Proving data integrity constraints, schema migration safety -**Default notation:** VCL-DT (VeriSimDB Query Language with Dependent Types) -**Promoted toolbar:** Query, Browse Entities, Check Drift, Normalise, Telemetry - ---- - -### 3. Programming Language Design & Development - -**Target audience:** Language designers, compiler writers, people building or -extending Eclexia, AffineScript, BetLang, or similar languages. - -**Key insight:** These users need to verify type system properties, prove compiler -transformations correct, test parser grammars, and browse ASTs. The proof engine is -heavily used but through a language-design lens (metatheory, not end-user proofs). - -| Pane | Visible | Size | Primary Content | -|-------------------|-----------|------|------------------------------| -| Pane-L (Symbolic) | Yes | 40% | Type rule editor, BNF viewer | -| Pane-N (Neural) | Yes | 25% | Inference trace, suggestions | -| Pane-W (World) | Yes | 35% | AST browser, test runner | -| ECHIDNA Panel | Expanded | — | Metatheory proofs | -| VeriSimDB Panel | Hidden | — | Not typically needed | -| Security/Panic | Collapsed | — | Parser fuzzing | - -**Pane-L details:** Type rule editor, grammar/BNF viewer, metatheory goal display. -**Pane-N details:** Neural stream, type inference trace, compilation suggestions. -**Pane-W details:** AST browser, test case runner, example program editor. -**ECHIDNA details:** Type safety, progress, preservation proofs; Coq/Lean -formalisation. - -**Default prover priority:** Coq → Lean 4 → Agda (metatheory-focused) -**Default notation:** Higher-order logic / dependent types -**Promoted toolbar:** Define Rule, Check Metatheory, Parse Example, Run Evaluator - ---- - -### 4. Protocol Design & Development - -**Target audience:** Network protocol designers, distributed systems engineers, -people working on Axel Protocol, TPCF, or similar specifications. - -**Key insight:** These users need to verify protocol properties (liveness, safety, -deadlock freedom), model state machines, check message format correctness, and -reason about concurrency. Many may not come from a formal methods background and -need the protocol-specific vocabulary (message flows, state transitions, invariants) -rather than generic proof terminology. - -| Pane | Visible | Size | Primary Content | -|-------------------|-----------|------|------------------------------| -| Pane-L (Symbolic) | Yes | 35% | State machine editor | -| Pane-N (Neural) | Yes | 25% | Deadlock warnings, analysis | -| Pane-W (World) | Yes | 40% | Message flow diagram | -| ECHIDNA Panel | Expanded | — | Model checking, liveness | -| VeriSimDB Panel | Collapsed | — | Protocol trace storage | -| Security/Panic | Expanded | — | Protocol fuzzing | - -**Pane-L details:** State machine editor, protocol invariants, message format specs. -**Pane-N details:** Neural stream, protocol analysis suggestions, deadlock warnings. -**Pane-W details:** Message flow diagram, simulation runner, test harness. -**ECHIDNA details:** TLA+/Z3 model checking, liveness/safety proofs. - -**Default prover priority:** Z3 → TLA+ (via ECHIDNA) → Spin → Isabelle -**Default notation:** Temporal logic (□ ◇ U), state predicates -**Promoted toolbar:** Define State, Add Transition, Check Liveness, Simulate, Fuzz - ---- - -### 5. General / Custom - -**Target audience:** Users whose workflow doesn't fit neatly into the above, or -who want to build their own layout. - -This is the current PanLL default — all panes visible at equal sizing, all sub-panels -collapsed. Users can drag pane borders to resize, expand/collapse any sub-panel, -and save their arrangement as a named custom layout. - ---- - -## Shared Core (Always Available Regardless of Layout) - -Every layout includes these foundational elements: - -| Element | Purpose | Always Visible? | -|---------|---------|-----------------| -| Neural Stream | ECHIDNA advisor + inference tokens | Yes (can be minimised) | -| Topology View | Binary Star diagram | Yes (toggleable) | -| ECHIDNA Health | Connection indicator + version | Yes (status bar) | -| Anti-Crash | Validation layer | Yes (background) | -| Vexometer | Operator vexation tracking | Yes (status bar) | -| Orbital Sync | Cross-pane synchronisation | Yes (background) | -| Contractiles | Contract enforcement | Yes (background) | -| Keyboard shortcuts | Global hotkeys | Yes | - ---- - -## Layout Extensibility - -### User-Defined Layouts - -Users can: -1. Start from any preset -2. Rearrange panes (drag borders, collapse/expand panels) -3. Save as named custom layout -4. Export/import layout configs (JSON) - -### Community Layouts - -Third parties can contribute layout presets as JSON files in a `layouts/` directory. -Each layout file specifies: - -```json -{ - "name": "Cryptographic Protocol Verification", - "description": "Optimised for verifying crypto protocol properties", - "author": "contributor-name", - "version": "1.0.0", - "base": "protocol", - "overrides": { - "echidna": { - "defaultProvers": ["z3", "tamarin"], - "defaultNotation": "applied-pi-calculus" - }, - "paneL": { - "defaultContent": "protocol-spec-editor", - "size": 40 - } - } -} -``` - -This follows the PanLL extensibility philosophy: the core ships with 4-5 useful -presets, but the system is open for community contribution without requiring code -changes. - ---- - -## Relationship to Progressive Sophistication - -The discipline layouts are **orthogonal** to the progressive sophistication levels -described in the companion design doc (Visual → Syntax → Logic → REPL). Within any -discipline layout, the user can still operate at any sophistication level: - -- A **database designer** at Level 1 drags query blocks visually -- A **database designer** at Level 3 writes VCL-DT with logical notation -- A **protocol designer** at Level 1 draws state machines visually -- A **protocol designer** at Level 4 writes raw TLA+ in a REPL - -The layout controls *what* is visible. The sophistication level controls *how* the -user interacts with it. - -``` - Layout (WHAT) - ┌──────────────────────────┐ - │ Logic │ DB │ Lang │ Proto │ - ┌────────────┼──────┼────┼──────┼───────┤ - │ Visual │ A │ B │ C │ D │ - S │ Syntax │ E │ F │ G │ H │ - O │ Logic │ I │ J │ K │ L │ - P │ REPL │ M │ N │ O │ P │ - H └────────────┴──────┴────┴──────┴───────┘ - (HOW) - -Each cell (A-P) is a valid configuration. -``` - ---- - -## Implementation Notes - -### Model Changes - -Add to `Model.res`: - -```rescript -/// Discipline layout presets for the global viewshift dropdown. -type disciplineLayout = - | LogicAndProofs - | DatabaseDesign - | LanguageDesign - | ProtocolDesign - | General - | Custom(string) // Named custom layout - -/// Layout configuration — which panes and sub-panels are visible and how -/// they are sized. This is the "recipe" that a disciplineLayout applies. -type layoutConfig = { - paneLSize: int, // Percentage width (0-100) - paneNSize: int, - paneWSize: int, - echidnaExpanded: bool, - verisimdbExpanded: bool, - securityExpanded: bool, - defaultProvers: array, - defaultNotation: string, - promotedActions: array, -} -``` - -### Message Changes - -```rescript -| SwitchLayout(disciplineLayout) -| SaveCustomLayout(string) -| LoadCustomLayout(string) -``` - -### Persistence - -Layout preference is stored in localStorage alongside existing PanLL state. -Custom layouts are stored as JSON in the user's config directory. - ---- - -## Open Questions - -1. **Should layouts also control the Information Humidity default?** E.g., database - designers might want Medium (show entity details) while protocol designers might - want Low (focus on state machine, shed noise). - -2. **Should the layout dropdown show a preview thumbnail?** A small wireframe showing - the pane arrangement before switching. - -3. **Can layouts be parameterised by project?** E.g., "When I open the VeriSimDB - project, auto-switch to Database Design layout." - -4. **Should community layouts live in a PanLL registry or just be files?** A registry - allows discovery but adds infrastructure burden. - ---- - -## References - -- Companion design: `DESIGN-2026-02-28-echidna-proof-ux.md` -- ReScript Evangeliser view layers: `developer-ecosystem/rescript-ecosystem/packages/tooling/evangeliser/src/Types.res` -- PanLL Model types: `panll/src/Model.res` -- PanLL three-pane architecture: `panll/docs/PANLL-COMPLETE-STATUS-2026-02-11.md` diff --git a/docs/design/DESIGN-2026-02-28-echidna-proof-ux.adoc b/docs/design/DESIGN-2026-02-28-echidna-proof-ux.adoc new file mode 100644 index 00000000..95af29b1 --- /dev/null +++ b/docs/design/DESIGN-2026-02-28-echidna-proof-ux.adoc @@ -0,0 +1,418 @@ +== DESIGN: ECHIDNA Proof UX — Switchable Syntax, Visual Proof Builder, and SLM Advisory + +*Date:* 2026-02-28 *Repo:* panll *Author:* Jonathan D.A. Jewell +*Status:* Design exploration (pre-implementation) + +=== Context + +With the mock ECHIDNA server in place (port 9000, +`+deno task mock:echidna+`), PanLL’s ECHIDNA panel can now be tested +end-to-end: sessions, tactics, suggestions, trust display. The next +question is: *how should the proof interaction feel?* + +The current flow is text-in, text-out — the user types a goal string, +picks a prover, and clicks through tactic suggestions. This works for +experts but creates a cliff for everyone else. The following design +explores three complementary approaches to make ECHIDNA’s proof engine +accessible at multiple skill levels. + +''''' + +=== Design Questions (from session dialogue) + +These questions arose during the design session and are preserved +verbatim because they capture real user concerns that others will share: + +____ +*Q1:* "`We need a switchable syntax linter, and a specific interface for +the solver, as well as the ability either to switch modes or use a +generalised syntax language to handle these proofs.`" +____ + +____ +*Q2:* "`Would adding an SLM to support this on top of that be helpful or +harmful (or at least too risky) so that the full power of ECHIDNA can be +leveraged?`" +____ + +____ +*Q3:* "`Maybe a bit like a mix of the CI/CD look for things to pass +through and you can assemble proof chains and it will notice what is +missing on the journey and off the back and forward propagation, +constraint propagation, and how/why queries?`" +____ + +____ +*Q4:* "`Perhaps that page can be switchable too with a logical notation +page that does a similar thing with the wider suite of logical notations +for support here.`" +____ + +____ +*Q5:* "`So they can enter into that box with linter support and +suggested corrections, but if they are getting more sophisticated, +switch to the logic and proofs subsystem of panes.`" +____ + +____ +*Q6:* "`Something like Blockly but for solvers would be fantastic.`" +____ + +____ +*Q7:* "`Can we take things we learn here to the ReScript Evangeliser, +and vice versa? That’s much more prioritised for pedagogy/heutagogy, but +I think the lessons might be valuable.`" +____ + +____ +*Q8:* "`As I ask questions can you use these as prompts to create the +documentary elements of the repo and the tool. Not the only stuff but +questions I have might be important too for others.`" +____ + +''''' + +=== Three-Layer Proof Interface + +==== Layer 1: Visual Proof Builder ("`Proof Pipeline`") + +*Inspiration:* CI/CD pipeline visualisations + Blockly + +A drag-and-drop canvas where proof obligations flow left-to-right +through stages, like a CI pipeline. Each stage is a proof step; +connectors show dependencies. + +.... +┌─────────────┐ ┌──────────────┐ ┌──────────────┐ +│ Goal │────▶│ Tactic 1 │────▶│ Subgoal A │──┐ +│ ∀n, n+0=n │ │ induction n │ │ 0+0=0 │ │ ┌──────────┐ +└─────────────┘ └──────────────┘ └──────────────┘ ├─▶│ QED ✓ │ + ┌──────────────┐ │ └──────────┘ + │ Subgoal B │──┘ + │ S n+0=S n │ + └──────────────┘ +.... + +*What the pipeline shows:* - *Green stages:* Obligations discharged +(goals solved) - *Amber stages:* In progress (goal exists, no tactic +applied yet) - *Red stages:* Failed/stuck (tactic didn’t close the goal) +- *Dashed connectors:* Missing steps the system detected via constraint +propagation - *Hovering a stage:* Shows the proof context (hypotheses, +goal, available lemmas) + +*Constraint propagation / gap detection:* - Forward propagation: "`If +you solve subgoal A, these lemmas become available`" - Backward +propagation: "`To close this goal, you need one of: [tactic list]`" - +*How queries:* "`How did this goal arise?`" → traces back through the +pipeline - *Why queries:* "`Why is this step needed?`" → shows what +depends on it downstream + +*Block types (Blockly-inspired palette):* + +[cols=",,",options="header",] +|=== +|Block Category |Examples |Colour +|Introduction |`+intro+`, `+intros+`, `+assume+` |Blue +|Elimination |`+destruct+`, `+inversion+`, `+case+` |Orange +|Rewriting |`+rewrite+`, `+simpl+`, `+unfold+` |Green +|Induction |`+induction+`, `+fix+`, `+cofix+` |Purple +|Automation |`+auto+`, `+omega+`, `+ring+`, `+decide+` |Teal +|SMT |`+check-sat+`, `+assert+`, `+simplify+` |Grey +|Custom |User-defined tactics/lemmas |Yellow +|=== + +Users can drag blocks from the palette onto pipeline stages, or click +suggestion chips that ECHIDNA’s ML advisor generates. + +==== Layer 2: Syntax-Aware Text Editor (Switchable Linter) + +For users who outgrow the visual builder, a text editor with switchable +syntax modes. The linter adapts to the active prover’s language: + +*Supported syntax modes:* + +[width="100%",cols="24%,38%,38%",options="header",] +|=== +|Mode |Language |Use Case +|Coq/Gallina |`+Theorem+`, `+Proof+`, `+Qed+` |Interactive theorem +proving + +|Lean 4 |`+theorem+`, `+by+`, `+simp+` |Modern ITP + +|Isabelle/Isar |`+lemma+`, `+proof+`, `+qed+` |Structured proofs + +|SMT-LIB 2 |`+(assert ...)+`, `+(check-sat)+` |SAT/SMT solving + +|Agda |Unicode, mixfix |Dependently typed + +|PanLL-Universal |See below |Cross-prover notation +|=== + +*PanLL-Universal syntax* is a generalised notation that translates to +any backend: + +.... +-- PanLL-Universal +goal: ∀ n : Nat, n + 0 = n +proof: + by induction on n + case zero: + simplify → done + case succ(n'): + simplify → done +.... + +The linter provides: - *Real-time error highlighting* with +prover-specific diagnostics - *Suggested corrections* (red squiggle → +click to fix) - *Auto-completion* for tactic names, lemma names, +identifiers - *Hover documentation* showing tactic signatures and +examples - *Switch mode button* in toolbar — changes syntax highlighting ++ linter rules + +==== Layer 3: Logical Notation Page (Switchable) + +A dedicated page (switchable from the proof builder) for working with +formal logical notation directly — propositional logic, first-order +logic, higher-order logic, linear logic, modal logic, etc. + +*Notation palettes:* + +[cols=",,",options="header",] +|=== +|Logic |Connectives |Quantifiers +|Propositional |∧ ∨ ¬ → ↔ ⊤ ⊥ |— +|First-Order |∧ ∨ ¬ → ↔ |∀ ∃ +|Higher-Order |+ type constructors |∀ ∃ λ Π Σ +|Linear |⊗ ⅋ ! ? ⊕ & |∀ ∃ +|Modal |□ ◇ |— +|Temporal |○ □ ◇ U W |— +|=== + +Users can *click symbols* from the palette to insert them, or use ASCII +fallbacks (`+/\+` for ∧, `+\/+` for ∨, `+forall+` for ∀, etc.). The page +can render the same proof in multiple notation styles simultaneously for +learning. + +''''' + +=== Progressive Sophistication Model + +The key insight (shared with the ReScript Evangeliser) is *progressive +disclosure*: + +.... +┌─────────────────────────────────────────────────────┐ +│ Level 1: Visual Proof Builder (Blockly-style) │ +│ → Drag blocks, see pipeline, click suggestions │ +│ → No syntax knowledge required │ +├─────────────────────────────────────────────────────┤ +│ Level 2: Syntax Editor (with linter + corrections) │ +│ → Type proof scripts with full IDE support │ +│ → Switchable syntax mode per prover │ +├─────────────────────────────────────────────────────┤ +│ Level 3: Logical Notation (formal logic symbols) │ +│ → Work directly with logical connectives │ +│ → Multi-logic palette (propositional → linear) │ +├─────────────────────────────────────────────────────┤ +│ Level 4: Raw Prover REPL (expert mode) │ +│ → Direct access to Coq/Lean/Z3 via ECHIDNA │ +│ → Full tactic language, no guardrails │ +└─────────────────────────────────────────────────────┘ +.... + +Users can switch freely between levels. The system remembers which level +each user prefers and nudges them upward when they demonstrate readiness +(e.g., "`You’ve used `+induction+` 5 times via blocks — want to try +typing it directly?`"). + +''''' + +=== SLM Analysis: Helpful, Harmful, or Too Risky? + +==== What an SLM Would Do + +A Small Language Model (1-3B parameters, e.g., Phi-3-mini, TinyLlama, or +a fine-tuned CodeGemma) would sit between the user and ECHIDNA to: + +[arabic] +. *Translate natural language to tactic scripts:* "`prove this by +splitting on n`" → `+induction n+` +. *Explain proof states in plain English:* "`You have two remaining +goals…`" +. *Suggest next steps based on partial proofs:* Context-aware tactic +ranking +. *Fix syntax errors before sending to the prover:* Pre-flight +correction + +==== Verdict: HELPFUL — but with strict guardrails + +*Benefits:* - Dramatically lowers the entry barrier (natural language → +formal proof) - Handles the "`PanLL-Universal → Coq/Lean`" translation +reliably - Can power the linter’s suggested corrections - Explains proof +failures in accessible language - Small enough to run locally (no cloud +dependency, offline-first) + +*Risks and mitigations:* + +[width="100%",cols="23%,35%,42%",options="header",] +|=== +|Risk |Severity |Mitigation +|SLM hallucinates a tactic |Medium |ECHIDNA validates every tactic +server-side; hallucinations just fail gracefully + +|SLM suggests unsound proof steps |Low |The prover is the ground truth, +not the SLM; suggestions are checked + +|SLM gives false confidence |Medium |Trust display shows ECHIDNA’s +verification, not SLM’s confidence + +|Model size / latency |Low |1-3B models run in <100ms on modern hardware + +|Maintenance burden |Medium |Use an off-the-shelf model with LoRA +fine-tuning, not a custom architecture +|=== + +*The key insight:* The SLM is an _input translator_ and _output +explainer_, never an _oracle_. ECHIDNA’s provers remain the source of +truth. The SLM’s output is always validated against the formal backend +before being shown to the user. This is fundamentally different from +using an LLM for code generation where hallucinations compile and run — +here, hallucinations are caught by the type checker / proof engine. + +*Architecture:* + +.... +User input (natural language / visual blocks / syntax) + │ + ▼ +┌─────────┐ ┌──────────┐ ┌──────────────┐ +│ SLM │────▶│ ECHIDNA │────▶│ Prover │ +│ (local) │ │ (API) │ │ (Coq/Lean/Z3)│ +└─────────┘ └──────────┘ └──────────────┘ + │ │ + │◀───────────────────────────────────┘ + │ (proof state / errors / success) + ▼ +User-facing explanation + trust display +.... + +''''' + +=== Cross-Pollination with ReScript Evangeliser + +The ReScript Evangeliser and PanLL’s ECHIDNA proof UX share deep +structural parallels: + +[width="100%",cols="20%,43%,37%",options="header",] +|=== +|Concept |ReScript Evangeliser |ECHIDNA Proof UX +|Progressive disclosure |RAW → FOLDED → GLYPHED → WYSIWYG |Visual → +Syntax → Logic → REPL + +|Celebrate-don’t-shame |"`Your JS is already doing X well!`" |"`Your +proof attempt is on track — 2 of 4 goals solved`" + +|Visual symbols (Glyphs) |Makaton-inspired: 🛡️ 🔄 🧩 |Proof pipeline +blocks: induction, rewrite, auto + +|Linter with corrections |JS → ReScript suggested rewrites +|Prover-syntax errors → suggested fixes + +|Confidence scoring |Pattern match confidence (0-1) |Tactic suggestion +confidence (0-1) + +|Gamification |Achievement badges, learning progress |Proof completion +badges, trust levels + +|SLM potential |"`What does this JS pattern do?`" |"`What tactic should +I try next?`" + +|Narrative system |celebrate/minimize/better/safety +|goal/context/suggestion/explanation +|=== + +*Transferable lessons:* + +[arabic] +. *From Evangeliser → ECHIDNA:* The narrative template system +(celebrate/minimize/ show-better) maps directly to proof feedback. +Instead of "`Your JavaScript already handles null checks — ReScript’s +Option makes them automatic`", write "`Your proof attempt already +handles the base case — induction will handle the rest automatically.`" +. *From ECHIDNA → Evangeliser:* The CI/CD pipeline view could teach +JavaScript → ReScript transformation as a pipeline: "`Your code flows +through these stages of improvement.`" The Blockly-style block palette +could let beginners drag ReScript patterns onto their JS code rather +than typing. +. *Shared infrastructure:* Both need a switchable syntax linter, +confidence-scored suggestions, progressive difficulty, and potentially +an SLM layer. Building this as a shared library (in ReScript, naturally) +would benefit both. + +''''' + +=== Implementation Phases + +==== Phase A: Mock server + demo data (THIS SESSION — DONE) + +* [x] Mock ECHIDNA on port 9000 +* [x] Demo neural tokens in Pane-N +* [x] All tests passing (19 Rust, 121 Deno, ReScript clean) + +==== Phase B: Visual Proof Builder (pipeline view) + +* [ ] Pipeline canvas component in ReScript/JSX +* [ ] Block palette with drag-drop +* [ ] Proof state → pipeline graph conversion +* [ ] Gap detection (constraint propagation) +* [ ] How/why query hover popups + +==== Phase C: Switchable Syntax Linter + +* [ ] Syntax mode selector in toolbar +* [ ] PanLL-Universal notation spec +* [ ] Per-prover syntax highlighting rules +* [ ] Error → suggested correction engine +* [ ] Coq, Lean, SMT-LIB, Agda mode definitions + +==== Phase D: Logical Notation Page + +* [ ] Symbol palette component +* [ ] Multi-logic rendering (propositional, FOL, HOL, linear, modal) +* [ ] ASCII fallback input +* [ ] Notation-switching toggle + +==== Phase E: SLM Integration (optional, deferred) + +* [ ] Model selection + local hosting (Deno/WASM or sidecar) +* [ ] NL → tactic translation pipeline +* [ ] Proof state → plain English explainer +* [ ] Guardrails: SLM output always validated against ECHIDNA + +''''' + +=== Open Questions + +[arabic] +. *Should PanLL-Universal be a new micro-language or a subset of an +existing one?* Candidates: Lean 4 syntax (already clean), a structured +markdown, or a custom DSL. +. *Where does the block palette live in PanLL’s three-pane model?* It +could be a Pane-L feature (symbolic/structural) or a new sub-pane within +the ECHIDNA panel. +. *Should the SLM be a Tauri sidecar (Rust-hosted GGUF) or a WASM +module?* Sidecar is simpler but adds binary size; WASM runs in the +webview but has memory limits. +. *How much of the switchable linter infrastructure can be shared with +the ReScript Evangeliser?* Both need mode-switching, confidence scoring, +and suggested corrections. + +''''' + +=== References + +* ReScript Evangeliser: +`+developer-ecosystem/rescript-ecosystem/packages/tooling/evangeliser/+` +* ECHIDNA mock server: `+panll/scripts/mock-echidna.ts+` +* PanLL Model types: `+panll/src/Model.res+` (lines 263-373) +* ECHIDNA update handlers: `+panll/src/Update.res+` (lines 700-1150) diff --git a/docs/design/DESIGN-2026-02-28-echidna-proof-ux.md b/docs/design/DESIGN-2026-02-28-echidna-proof-ux.md deleted file mode 100644 index 18b19022..00000000 --- a/docs/design/DESIGN-2026-02-28-echidna-proof-ux.md +++ /dev/null @@ -1,337 +0,0 @@ -# DESIGN: ECHIDNA Proof UX — Switchable Syntax, Visual Proof Builder, and SLM Advisory - -**Date:** 2026-02-28 -**Repo:** panll -**Author:** Jonathan D.A. Jewell -**Status:** Design exploration (pre-implementation) - -## Context - -With the mock ECHIDNA server in place (port 9000, `deno task mock:echidna`), PanLL's -ECHIDNA panel can now be tested end-to-end: sessions, tactics, suggestions, trust -display. The next question is: **how should the proof interaction feel?** - -The current flow is text-in, text-out — the user types a goal string, picks a prover, -and clicks through tactic suggestions. This works for experts but creates a cliff for -everyone else. The following design explores three complementary approaches to make -ECHIDNA's proof engine accessible at multiple skill levels. - ---- - -## Design Questions (from session dialogue) - -These questions arose during the design session and are preserved verbatim because -they capture real user concerns that others will share: - -> **Q1:** "We need a switchable syntax linter, and a specific interface for the -> solver, as well as the ability either to switch modes or use a generalised syntax -> language to handle these proofs." - -> **Q2:** "Would adding an SLM to support this on top of that be helpful or harmful -> (or at least too risky) so that the full power of ECHIDNA can be leveraged?" - -> **Q3:** "Maybe a bit like a mix of the CI/CD look for things to pass through and -> you can assemble proof chains and it will notice what is missing on the journey and -> off the back and forward propagation, constraint propagation, and how/why queries?" - -> **Q4:** "Perhaps that page can be switchable too with a logical notation page that -> does a similar thing with the wider suite of logical notations for support here." - -> **Q5:** "So they can enter into that box with linter support and suggested -> corrections, but if they are getting more sophisticated, switch to the logic and -> proofs subsystem of panes." - -> **Q6:** "Something like Blockly but for solvers would be fantastic." - -> **Q7:** "Can we take things we learn here to the ReScript Evangeliser, and vice -> versa? That's much more prioritised for pedagogy/heutagogy, but I think the lessons -> might be valuable." - -> **Q8:** "As I ask questions can you use these as prompts to create the documentary -> elements of the repo and the tool. Not the only stuff but questions I have might be -> important too for others." - ---- - -## Three-Layer Proof Interface - -### Layer 1: Visual Proof Builder ("Proof Pipeline") - -**Inspiration:** CI/CD pipeline visualisations + Blockly - -A drag-and-drop canvas where proof obligations flow left-to-right through stages, -like a CI pipeline. Each stage is a proof step; connectors show dependencies. - -``` -┌─────────────┐ ┌──────────────┐ ┌──────────────┐ -│ Goal │────▶│ Tactic 1 │────▶│ Subgoal A │──┐ -│ ∀n, n+0=n │ │ induction n │ │ 0+0=0 │ │ ┌──────────┐ -└─────────────┘ └──────────────┘ └──────────────┘ ├─▶│ QED ✓ │ - ┌──────────────┐ │ └──────────┘ - │ Subgoal B │──┘ - │ S n+0=S n │ - └──────────────┘ -``` - -**What the pipeline shows:** -- **Green stages:** Obligations discharged (goals solved) -- **Amber stages:** In progress (goal exists, no tactic applied yet) -- **Red stages:** Failed/stuck (tactic didn't close the goal) -- **Dashed connectors:** Missing steps the system detected via constraint propagation -- **Hovering a stage:** Shows the proof context (hypotheses, goal, available lemmas) - -**Constraint propagation / gap detection:** -- Forward propagation: "If you solve subgoal A, these lemmas become available" -- Backward propagation: "To close this goal, you need one of: [tactic list]" -- **How queries:** "How did this goal arise?" → traces back through the pipeline -- **Why queries:** "Why is this step needed?" → shows what depends on it downstream - -**Block types (Blockly-inspired palette):** - -| Block Category | Examples | Colour | -|----------------|----------|--------| -| Introduction | `intro`, `intros`, `assume` | Blue | -| Elimination | `destruct`, `inversion`, `case` | Orange | -| Rewriting | `rewrite`, `simpl`, `unfold` | Green | -| Induction | `induction`, `fix`, `cofix` | Purple | -| Automation | `auto`, `omega`, `ring`, `decide` | Teal | -| SMT | `check-sat`, `assert`, `simplify` | Grey | -| Custom | User-defined tactics/lemmas | Yellow | - -Users can drag blocks from the palette onto pipeline stages, or click suggestion -chips that ECHIDNA's ML advisor generates. - -### Layer 2: Syntax-Aware Text Editor (Switchable Linter) - -For users who outgrow the visual builder, a text editor with switchable syntax -modes. The linter adapts to the active prover's language: - -**Supported syntax modes:** - -| Mode | Language | Use Case | -|------|----------|----------| -| Coq/Gallina | `Theorem`, `Proof`, `Qed` | Interactive theorem proving | -| Lean 4 | `theorem`, `by`, `simp` | Modern ITP | -| Isabelle/Isar | `lemma`, `proof`, `qed` | Structured proofs | -| SMT-LIB 2 | `(assert ...)`, `(check-sat)` | SAT/SMT solving | -| Agda | Unicode, mixfix | Dependently typed | -| PanLL-Universal | See below | Cross-prover notation | - -**PanLL-Universal syntax** is a generalised notation that translates to any backend: - -``` --- PanLL-Universal -goal: ∀ n : Nat, n + 0 = n -proof: - by induction on n - case zero: - simplify → done - case succ(n'): - simplify → done -``` - -The linter provides: -- **Real-time error highlighting** with prover-specific diagnostics -- **Suggested corrections** (red squiggle → click to fix) -- **Auto-completion** for tactic names, lemma names, identifiers -- **Hover documentation** showing tactic signatures and examples -- **Switch mode button** in toolbar — changes syntax highlighting + linter rules - -### Layer 3: Logical Notation Page (Switchable) - -A dedicated page (switchable from the proof builder) for working with formal logical -notation directly — propositional logic, first-order logic, higher-order logic, -linear logic, modal logic, etc. - -**Notation palettes:** - -| Logic | Connectives | Quantifiers | -|-------|-------------|-------------| -| Propositional | ∧ ∨ ¬ → ↔ ⊤ ⊥ | — | -| First-Order | ∧ ∨ ¬ → ↔ | ∀ ∃ | -| Higher-Order | + type constructors | ∀ ∃ λ Π Σ | -| Linear | ⊗ ⅋ ! ? ⊕ & | ∀ ∃ | -| Modal | □ ◇ | — | -| Temporal | ○ □ ◇ U W | — | - -Users can **click symbols** from the palette to insert them, or use ASCII fallbacks -(`/\` for ∧, `\/` for ∨, `forall` for ∀, etc.). The page can render the same proof -in multiple notation styles simultaneously for learning. - ---- - -## Progressive Sophistication Model - -The key insight (shared with the ReScript Evangeliser) is **progressive disclosure**: - -``` -┌─────────────────────────────────────────────────────┐ -│ Level 1: Visual Proof Builder (Blockly-style) │ -│ → Drag blocks, see pipeline, click suggestions │ -│ → No syntax knowledge required │ -├─────────────────────────────────────────────────────┤ -│ Level 2: Syntax Editor (with linter + corrections) │ -│ → Type proof scripts with full IDE support │ -│ → Switchable syntax mode per prover │ -├─────────────────────────────────────────────────────┤ -│ Level 3: Logical Notation (formal logic symbols) │ -│ → Work directly with logical connectives │ -│ → Multi-logic palette (propositional → linear) │ -├─────────────────────────────────────────────────────┤ -│ Level 4: Raw Prover REPL (expert mode) │ -│ → Direct access to Coq/Lean/Z3 via ECHIDNA │ -│ → Full tactic language, no guardrails │ -└─────────────────────────────────────────────────────┘ -``` - -Users can switch freely between levels. The system remembers which level each user -prefers and nudges them upward when they demonstrate readiness (e.g., "You've used -`induction` 5 times via blocks — want to try typing it directly?"). - ---- - -## SLM Analysis: Helpful, Harmful, or Too Risky? - -### What an SLM Would Do - -A Small Language Model (1-3B parameters, e.g., Phi-3-mini, TinyLlama, or a -fine-tuned CodeGemma) would sit between the user and ECHIDNA to: - -1. **Translate natural language to tactic scripts:** "prove this by splitting on n" → `induction n` -2. **Explain proof states in plain English:** "You have two remaining goals..." -3. **Suggest next steps based on partial proofs:** Context-aware tactic ranking -4. **Fix syntax errors before sending to the prover:** Pre-flight correction - -### Verdict: HELPFUL — but with strict guardrails - -**Benefits:** -- Dramatically lowers the entry barrier (natural language → formal proof) -- Handles the "PanLL-Universal → Coq/Lean" translation reliably -- Can power the linter's suggested corrections -- Explains proof failures in accessible language -- Small enough to run locally (no cloud dependency, offline-first) - -**Risks and mitigations:** - -| Risk | Severity | Mitigation | -|------|----------|------------| -| SLM hallucinates a tactic | Medium | ECHIDNA validates every tactic server-side; hallucinations just fail gracefully | -| SLM suggests unsound proof steps | Low | The prover is the ground truth, not the SLM; suggestions are checked | -| SLM gives false confidence | Medium | Trust display shows ECHIDNA's verification, not SLM's confidence | -| Model size / latency | Low | 1-3B models run in <100ms on modern hardware | -| Maintenance burden | Medium | Use an off-the-shelf model with LoRA fine-tuning, not a custom architecture | - -**The key insight:** The SLM is an *input translator* and *output explainer*, never -an *oracle*. ECHIDNA's provers remain the source of truth. The SLM's output is always -validated against the formal backend before being shown to the user. This is -fundamentally different from using an LLM for code generation where hallucinations -compile and run — here, hallucinations are caught by the type checker / proof engine. - -**Architecture:** -``` -User input (natural language / visual blocks / syntax) - │ - ▼ -┌─────────┐ ┌──────────┐ ┌──────────────┐ -│ SLM │────▶│ ECHIDNA │────▶│ Prover │ -│ (local) │ │ (API) │ │ (Coq/Lean/Z3)│ -└─────────┘ └──────────┘ └──────────────┘ - │ │ - │◀───────────────────────────────────┘ - │ (proof state / errors / success) - ▼ -User-facing explanation + trust display -``` - ---- - -## Cross-Pollination with ReScript Evangeliser - -The ReScript Evangeliser and PanLL's ECHIDNA proof UX share deep structural parallels: - -| Concept | ReScript Evangeliser | ECHIDNA Proof UX | -|---------|---------------------|------------------| -| Progressive disclosure | RAW → FOLDED → GLYPHED → WYSIWYG | Visual → Syntax → Logic → REPL | -| Celebrate-don't-shame | "Your JS is already doing X well!" | "Your proof attempt is on track — 2 of 4 goals solved" | -| Visual symbols (Glyphs) | Makaton-inspired: 🛡️ 🔄 🧩 | Proof pipeline blocks: induction, rewrite, auto | -| Linter with corrections | JS → ReScript suggested rewrites | Prover-syntax errors → suggested fixes | -| Confidence scoring | Pattern match confidence (0-1) | Tactic suggestion confidence (0-1) | -| Gamification | Achievement badges, learning progress | Proof completion badges, trust levels | -| SLM potential | "What does this JS pattern do?" | "What tactic should I try next?" | -| Narrative system | celebrate/minimize/better/safety | goal/context/suggestion/explanation | - -**Transferable lessons:** - -1. **From Evangeliser → ECHIDNA:** The narrative template system (celebrate/minimize/ - show-better) maps directly to proof feedback. Instead of "Your JavaScript already - handles null checks — ReScript's Option makes them automatic", write "Your proof - attempt already handles the base case — induction will handle the rest automatically." - -2. **From ECHIDNA → Evangeliser:** The CI/CD pipeline view could teach JavaScript → - ReScript transformation as a pipeline: "Your code flows through these stages of - improvement." The Blockly-style block palette could let beginners drag ReScript - patterns onto their JS code rather than typing. - -3. **Shared infrastructure:** Both need a switchable syntax linter, confidence-scored - suggestions, progressive difficulty, and potentially an SLM layer. Building this - as a shared library (in ReScript, naturally) would benefit both. - ---- - -## Implementation Phases - -### Phase A: Mock server + demo data (THIS SESSION — DONE) -- [x] Mock ECHIDNA on port 9000 -- [x] Demo neural tokens in Pane-N -- [x] All tests passing (19 Rust, 121 Deno, ReScript clean) - -### Phase B: Visual Proof Builder (pipeline view) -- [ ] Pipeline canvas component in ReScript/JSX -- [ ] Block palette with drag-drop -- [ ] Proof state → pipeline graph conversion -- [ ] Gap detection (constraint propagation) -- [ ] How/why query hover popups - -### Phase C: Switchable Syntax Linter -- [ ] Syntax mode selector in toolbar -- [ ] PanLL-Universal notation spec -- [ ] Per-prover syntax highlighting rules -- [ ] Error → suggested correction engine -- [ ] Coq, Lean, SMT-LIB, Agda mode definitions - -### Phase D: Logical Notation Page -- [ ] Symbol palette component -- [ ] Multi-logic rendering (propositional, FOL, HOL, linear, modal) -- [ ] ASCII fallback input -- [ ] Notation-switching toggle - -### Phase E: SLM Integration (optional, deferred) -- [ ] Model selection + local hosting (Deno/WASM or sidecar) -- [ ] NL → tactic translation pipeline -- [ ] Proof state → plain English explainer -- [ ] Guardrails: SLM output always validated against ECHIDNA - ---- - -## Open Questions - -1. **Should PanLL-Universal be a new micro-language or a subset of an existing one?** - Candidates: Lean 4 syntax (already clean), a structured markdown, or a custom DSL. - -2. **Where does the block palette live in PanLL's three-pane model?** It could be a - Pane-L feature (symbolic/structural) or a new sub-pane within the ECHIDNA panel. - -3. **Should the SLM be a Tauri sidecar (Rust-hosted GGUF) or a WASM module?** Sidecar - is simpler but adds binary size; WASM runs in the webview but has memory limits. - -4. **How much of the switchable linter infrastructure can be shared with the ReScript - Evangeliser?** Both need mode-switching, confidence scoring, and suggested corrections. - ---- - -## References - -- ReScript Evangeliser: `developer-ecosystem/rescript-ecosystem/packages/tooling/evangeliser/` -- ECHIDNA mock server: `panll/scripts/mock-echidna.ts` -- PanLL Model types: `panll/src/Model.res` (lines 263-373) -- ECHIDNA update handlers: `panll/src/Update.res` (lines 700-1150) diff --git a/docs/design/DESIGN-2026-02-28-infrastructure-requirements.adoc b/docs/design/DESIGN-2026-02-28-infrastructure-requirements.adoc new file mode 100644 index 00000000..9e11cc51 --- /dev/null +++ b/docs/design/DESIGN-2026-02-28-infrastructure-requirements.adoc @@ -0,0 +1,601 @@ +== DESIGN: PanLL Infrastructure Requirements — Accessibility, i18n, Interoperability + +*Date:* 2026-02-28 *Repo:* panll *Author:* Jonathan D.A. Jewell +*Status:* Architectural requirements (binding on all future +implementation) + +=== Context + +PanLL is a workbench for formal methods, database design, language +design, and protocol engineering. These disciplines are inherently +international, academic, and collaborative. The tool must be accessible, +translatable, and interoperable with the research ecosystem from the +start — not as afterthoughts. + +This document establishes infrastructure requirements that apply across +all features and all discipline layouts. These are not "`nice to haves`" +— they are architectural constraints. + +=== Design Questions (from session dialogue) + +____ +"`Can we add interoperability with Zotero and also make sure it has the +full suite of accessibility features across the board, and stuff that is +going to support Pandoc, agrep, internationalisation, OCR and so on in +its design?`" +____ + +''''' + +=== 1. Accessibility (WCAG 2.3 — Binding Commitment) + +==== Target Conformance + +[width="100%",cols="11%,17%,72%",options="header",] +|=== +|Level |Commitment |Notes +|A |Mandatory |Every feature must pass before merge +|AA |Target |Default standard for all new work +|AAA |Best-effort |Where achievable without hampering functionality +|=== + +*Trustfile implication:* The PanLL Trustfile (when created) must declare +WCAG 2.3 AA as the accessibility commitment. CI should enforce automated +checks. + +==== Requirements by Category + +===== Perceivable (WCAG Principle 1) + +[width="100%",cols="36%,10%,54%",options="header",] +|=== +|Requirement |WCAG |PanLL Application +|Text alternatives |1.1.1 A |All icons, glyphs, proof pipeline stages + +|Captions for audio |1.2.2 A |Voice collaboration transcription + +|Audio description |1.2.5 AA |Proof pipeline state narration + +|Colour not sole indicator |1.4.1 A |Green/amber/red + icons + text +labels + +|Contrast ratio 4.5:1 |1.4.3 AA |All text including proof notation + +|Contrast ratio 3:1 (large) |1.4.3 AA |Headers, block labels, toolbar +buttons + +|Resize to 200% |1.4.4 AA |All panes reflow without horizontal scroll + +|Reflow at 400% |1.4.10 AA |Single-column layout at 400% zoom + +|Text spacing adjustable |1.4.12 AA |No clipping when +line-height/spacing changed + +|Non-text contrast 3:1 |1.4.11 AA |Pipeline connectors, block borders, +charts +|=== + +*Proof pipeline specifics:* - Green/amber/red stages must ALSO show: +checkmark/clock/cross icons - Screen reader: "`Goal 1: solved. Goal 2: +in progress. Goal 3: pending.`" - Logical symbols (∀, ∃, →) must have +aria-labels ("`for all`", "`there exists`", "`implies`") - Drift heatmap +must have text-mode alternative (table of values) + +===== Operable (WCAG Principle 2) + +[width="100%",cols="37%,11%,52%",options="header",] +|=== +|Requirement |WCAG |PanLL Application +|Keyboard accessible |2.1.1 A |Every feature usable without mouse + +|No keyboard traps |2.1.2 A |Escape always exits modals/menus + +|Focus order logical |2.4.3 A |Tab order follows pane flow (L → N → W) + +|Focus visible |2.4.7 AA |2px solid outline on focused elements + +|Skip to content |2.4.1 A |Skip links for each pane + +|Pointer cancellation |2.5.2 A |Drag-drop has up-event cancellation + +|Dragging alternative |2.5.7 AA |Block palette: keyboard select + Enter + +|Timing adjustable |2.2.1 A |No auto-dismiss toasts; user controls +timing + +|Reduced motion |2.3.3 AAA |Respect `+prefers-reduced-motion+` +|=== + +*Proof pipeline specifics:* - Arrow keys navigate between pipeline +stages - Enter applies selected tactic or expands goal details - Tab +moves between the palette, pipeline, and goal display - Drag-and-drop +blocks have keyboard alternative: select block with Enter, Tab to target +stage, Enter to place - The Blockly-style palette is navigable with +arrow keys (category → block → apply) + +===== Understandable (WCAG Principle 3) + +[width="100%",cols="37%,11%,52%",options="header",] +|=== +|Requirement |WCAG |PanLL Application +|Language of page |3.1.1 A |`+lang+` attribute on root element + +|Language of parts |3.1.2 AA |Proof notation in `+lang="x-math"+` + +|On focus no change |3.2.1 A |Layout switching requires explicit action + +|Consistent navigation |3.2.3 AA |Toolbar position stable across layouts + +|Error identification |3.3.1 A |Proof errors identified in text, not +colour + +|Error suggestion |3.3.3 AA |Linter suggests corrections with +description + +|Labels or instructions |3.3.2 A |Goal input, tactic input, query input +|=== + +===== Robust (WCAG Principle 4) + +[width="100%",cols="37%,11%,52%",options="header",] +|=== +|Requirement |WCAG |PanLL Application +|Valid HTML |4.1.1 A |Clean semantic HTML from Tea_Html +|Name, role, value |4.1.2 A |ARIA roles on all custom widgets +|Status messages |4.1.3 AA |`+aria-live+` for proof state changes +|=== + +==== Implementation Approach + +*Existing foundation:* Tea_Vdom already has 10 ARIA attribute functions. +These must be used consistently across ALL components — the gap between +"`functions exist`" and "`functions are applied`" must be closed. + +*Testing:* - Automated: axe-core via Playwright in CI (catches ~30-40% +of issues) - Manual: screen reader testing with NVDA (Windows), Orca +(Linux), VoiceOver (macOS) - Keyboard: every feature must be testable +with keyboard-only navigation + +*CSS requirements:* + +[source,css] +---- +@media (prefers-reduced-motion: reduce) { + *, *::before, *::after { + animation-duration: 0.001ms !important; + transition-duration: 0.001ms !important; + } +} + +@media (prefers-contrast: more) { + :root { + --border-width: 2px; + --focus-outline: 3px solid; + } +} + +@media (prefers-color-scheme: dark) { + /* dark mode variables */ +} +---- + +''''' + +=== 2. Internationalisation (i18n) + +==== Current State + +META.scm documents: English-only for v0.x, i18n framework planned for +v1.0, RTL support as future work. + +==== Architecture + +*Framework:* polyglot-i18n + LOL (Localisation Overlay Language) + +Why polyglot-i18n + LOL over Project Fluent/gettext/ICU: - +Hyperpolymath-native i18n stack — dogfooded across the estate - LOL +handles plurals, gender, and grammatical cases cleanly - polyglot-i18n +provides the runtime loader and locale resolution - ReScript integration +via the polyglot-i18n ReScript bindings - No dependency on Mozilla’s +`+@fluent/bundle+` npm package + +*File structure:* + +.... +locales/ +├── en/ # English (source) +│ ├── app.lol # Core UI strings +│ ├── proofs.lol # Proof-specific terminology +│ ├── database.lol # Database-specific terminology +│ ├── protocols.lol # Protocol-specific terminology +│ └── accessibility.lol # Screen reader announcements +├── fr/ +├── de/ +├── ja/ +├── ar/ # RTL +├── zh-Hans/ +└── ... +.... + +*Example LOL file (`+locales/en/proofs.lol+`):* + +.... +proof-goal-solved = Goal { $number } solved +proof-goals-remaining = { $count -> + [one] { $count } goal remaining + *[other] { $count } goals remaining +} +proof-status-success = Proof complete — all goals discharged +proof-status-failed = Proof failed at goal { $goal } +tactic-suggestion = Suggested tactic: { $name } (confidence { $confidence }) +.... + +*Localisation of mathematical notation:* Mathematical symbols (∀, ∃, →, +∧, ∨) are universal and do NOT get translated. But their +spoken/screen-reader forms DO: + +[cols=",,,",options="header",] +|=== +|Symbol |English |French |German +|∀ |for all |pour tout |für alle +|∃ |there exists |il existe |es existiert +|→ |implies |implique |impliziert +|∧ |and |et |und +|∨ |or |ou |oder +|=== + +==== RTL Support + +Arabic, Hebrew, Farsi, Urdu require right-to-left layout. Critically, +mixed-direction content is common in proofs (RTL prose + LTR +mathematical notation): + +[source,html] +---- +
+ + نثبت أن ∀ n : ℕ, n + 0 = n + +
+---- + +PanLL’s pane system must handle `+dir="rtl"+` on the root and use +logical CSS properties (`+inline-start+`/`+inline-end+` instead of +`+left+`/`+right+`). + +''''' + +=== 3. Zotero Integration + +==== Why Zotero + +Proofs cite papers. Database schemas reference standards. Protocols +reference RFCs. Zotero is the dominant open-source reference manager in +academia. Integration means users don’t need to leave PanLL to find or +cite a reference. + +==== Integration Points + +[width="100%",cols="31%,35%,34%",options="header",] +|=== +|Feature |Mechanism |Notes +|Search user’s library |Zotero Web API (v3) |Read-only, API key auth + +|Insert citation |CSL-JSON → formatted cite |Into proof comments/docs + +|Link theorem to paper |Attach Zotero item key |"`This lemma from +[Smith24]`" + +|Browse collections |Zotero API `+/collections+` |Filtered by discipline + +|Export bibliography |CSL-JSON → Pandoc → BibTeX |For paper writing + +|Local Zotero (optional) |Zotero local API (port 23119) |No cloud +dependency +|=== + +==== Zotero API Details + +*Authentication:* API key (per-user, stored in PanLL config) + +*Key endpoints:* + +.... +GET /users/{userId}/items?q={searchTerm} # Search library +GET /users/{userId}/items/{itemKey} # Get item details +GET /users/{userId}/collections # List collections +GET /users/{userId}/items/{itemKey}/children # Attachments (PDFs) +.... + +*CSL-JSON* is the interchange format — Zotero exports it, Pandoc +consumes it, and PanLL can render formatted citations from it. + +==== Local-First Design + +Zotero 7 exposes a local HTTP API on port 23119 (when Zotero is +running). PanLL should prefer the local API (no network dependency, +faster) and fall back to the web API. This aligns with PanLL’s +offline-first principle. + +.... +1. Try localhost:23119 (Zotero desktop running locally) +2. Fall back to api.zotero.org (cloud, requires API key) +3. Fall back to manual BibTeX/CSL-JSON file import +.... + +''''' + +=== 4. Pandoc Integration + +==== Why Pandoc + +PanLL produces proof scripts, design documents, query results, protocol +specs. These need to be exportable in multiple formats for papers, +reports, presentations, and archival. Pandoc is the universal document +converter. + +==== Export Targets + +[cols=",",options="header",] +|=== +|Format |Use Case +|LaTeX/PDF |Academic papers, proof appendices +|HTML |Web publishing, sharing +|Markdown |GitHub/GitLab documentation +|AsciiDoc |RSR documentation standard +|DOCX |Collaboration with Word users +|EPUB |Long-form documentation +|Typst |Modern alternative to LaTeX +|Djot |Lightweight markup (hyperpolymath standard) +|=== + +==== Integration Approach + +*Pandoc as Tauri sidecar or Deno subprocess:* + +.... +PanLL proof script / document + │ + ▼ + Internal representation (Pandoc AST JSON) + │ + ▼ + pandoc --from json --to {format} --citeproc --bibliography refs.json + │ + ▼ + Output file (PDF, HTML, DOCX, etc.) +.... + +*`+--citeproc+`* handles Zotero citations automatically — CSL-JSON from +Zotero → Pandoc citeproc → formatted bibliography in output. + +*Custom Pandoc filters* (Lua) for PanLL-specific content: - Proof +pipeline → LaTeX `+proof+` environment - Tactic sequences → +`+lstlisting+` with Coq/Lean syntax - Trust level badges → coloured +boxes in PDF - ECHIDNA dispatch results → formatted tables + +==== Pandoc AST as Intermediate Representation + +Rather than building format-specific exporters for each output type, +PanLL should produce Pandoc AST JSON as its universal export format. +This means: - One export path, many output formats - New formats added +by installing Pandoc writers (no PanLL code changes) - Community can +write custom Pandoc filters for domain-specific rendering + +''''' + +=== 5. Fuzzy Search (agrep / Approximate Matching) + +==== Why Fuzzy Search + +Users mistype tactic names. Theorem names are long and easy to get +wrong. Database entity names have variations. Protocol state names may +be remembered imprecisely. Exact search fails silently; fuzzy search +finds what you meant. + +*Accessibility connection:* Users with motor impairments, dyslexia, or +who are typing in a non-native language benefit enormously from +approximate matching. + +==== Implementation + +*Algorithm:* Levenshtein distance with BK-tree index for fast lookup + +*Where fuzzy search applies:* + +[width="100%",cols="39%,44%,17%",options="header",] +|=== +|Context |Search corpus |Threshold +|Tactic name input |Prover’s tactic catalog |Edit distance ≤ 2 +|Theorem search |Mathlib / theorem corpus |Edit distance ≤ 3 +|Entity name lookup |VeriSimDB entity list |Edit distance ≤ 2 +|Protocol state search |State machine state names |Edit distance ≤ 2 +|Command palette |All PanLL commands |Subsequence match +|=== + +*Behaviour:* + +.... +User types: "inducton" +Fuzzy match: "induction" (distance 1) +UI shows: "induction" with subtle correction indicator + +User types: "Nat.add_como" +Fuzzy match: "Nat.add_comm" (distance 2) +UI shows: "Did you mean Nat.add_comm?" +.... + +*ReScript implementation:* Pure ReScript Levenshtein function (~30 +lines). No external dependency needed for the core algorithm. For large +corpora (Mathlib’s 100k+ theorems), a BK-tree or trigram index for +sub-millisecond lookup. + +''''' + +=== 6. OCR (Optical Character Recognition) + +==== Why OCR + +Researchers work with papers (PDF), textbooks (scanned), handwritten +notes (whiteboard photos), and legacy documents. Importing proof goals, +theorem statements, or protocol specs from these sources should be +seamless. + +*Mathematical OCR* is a specific sub-problem — standard OCR (Tesseract) +handles prose well but struggles with mathematical notation. Specialised +tools exist. + +==== Integration Approach + +[width="99%",cols="27%,42%,31%",options="header",] +|=== +|Source |Tool |Output +|PDF (digital) |Pandoc / pdftotext |Structured text +|PDF (scanned) |Tesseract OCR + layout |Raw text + positions +|Mathematical |Mathpix / InftyReader / Nougat |LaTeX notation +|Handwritten |Mathpix or MyScript |LaTeX notation +|Whiteboard photo |Tesseract + preprocessing |Raw text +|=== + +*Workflow:* + +.... +1. User imports image/PDF into PanLL (drag-drop or file picker) +2. PanLL detects content type (prose, math, mixed) +3. For math: send to math-OCR engine → LaTeX output +4. Convert LaTeX to PanLL-Universal or prover syntax +5. User reviews and corrects in the syntax editor +6. Corrected text becomes proof goal or constraint +.... + +*Local-first:* Tesseract runs locally (no cloud dependency). For +mathematical OCR, Nougat (Meta’s open-source scientific document OCR) +runs locally on GPU. Mathpix is cloud-based and optional. + +*Accessibility note:* OCR also enables PanLL to describe images to +screen reader users — "`This image contains the formula: for all n, n + +0 = n.`" + +''''' + +=== 7. Cross-Cutting Concerns + +==== Offline-First Principle + +Every feature in this document must work offline except where network +access is inherently required: + +[width="100%",cols="27%,15%,58%",options="header",] +|=== +|Feature |Offline? |Notes +|Accessibility |Yes |Fully local +|i18n |Yes |Locale files bundled +|Zotero (local) |Yes |localhost:23119 +|Zotero (cloud) |No |Requires api.zotero.org +|Pandoc export |Yes |Pandoc binary bundled or local install +|Fuzzy search |Yes |Pure ReScript, no network +|OCR (Tesseract) |Yes |Local binary +|OCR (Nougat) |Yes |Local model +|OCR (Mathpix) |No |Cloud API +|Collaboration |No |Requires Phoenix server +|=== + +==== Trustfile Obligations + +When the PanLL Trustfile is created, it must declare: + +.... +(accessibility + (standard "WCAG 2.3") + (conformance-level "AA") + (target-level "AAA where feasible") + (testing "automated axe-core + manual screen reader") + (policy "no feature ships without A compliance")) + +(internationalisation + (framework "polyglot-i18n + LOL") + (source-language "en") + (rtl-support "planned v1.0") + (math-notation "universal, not translated")) + +(interoperability + (citation-manager "Zotero API v3 + local API") + (document-export "Pandoc AST JSON") + (search "fuzzy Levenshtein, edit distance ≤ 3") + (ocr "Tesseract local + Nougat for math")) +.... + +==== Performance Budget + +Infrastructure features must not degrade the core experience: + +[cols=",",options="header",] +|=== +|Feature |Budget +|Fuzzy search |< 10ms for 10k-item corpus +|i18n string lookup |< 1ms per string +|ARIA attribute render |negligible (HTML attrs) +|Pandoc export |< 5s for typical proof doc +|OCR |< 30s for a page of math +|Zotero search |< 2s (local), < 5s (cloud) +|=== + +''''' + +=== Implementation Priority + +[cols=",,,",options="header",] +|=== +|Feature |Priority |Phase |Dependency +|ARIA pass (close gap) |P0 |Immediate |Existing components +|`+prefers-reduced-motion+` |P0 |Immediate |CSS only +|`+prefers-contrast+` |P0 |Immediate |CSS only +|Keyboard navigation audit |P0 |Immediate |Existing components +|Fuzzy search |P1 |Next sprint |Pure ReScript +|Pandoc export |P1 |Next sprint |Pandoc binary +|polyglot-i18n + LOL setup |P2 |v1.0 prep |polyglot-i18n bindings +|Zotero local API |P2 |v1.0 prep |HTTP client +|OCR (Tesseract) |P3 |v1.0+ |Tesseract binary +|OCR (math/Nougat) |P3 |v1.0+ |GPU, model download +|RTL layout |P3 |v1.0+ |LOL + CSS logical +|=== + +''''' + +=== Open Questions + +[arabic] +. *Should PanLL bundle Pandoc, or require it as a system dependency?* +Bundling adds ~80 MB to the Tauri binary but eliminates "`install Pandoc +first`" friction. +. *Should fuzzy search be a standalone ReScript module publishable to +the ecosystem?* Other hyperpolymath tools (ReScript Evangeliser, NQC) +could use it. +. *Is Nougat (Meta’s math OCR) the right choice, or should we wait for +better open models?* Nougat is good but requires a GPU for reasonable +speed. +. *Should Zotero integration be a PanLL core feature or a plugin?* Core +means everyone gets it; plugin means non-academics don’t pay the code +size cost. +. *Which screen readers should be the primary test targets?* Orca +(Linux) is most relevant for the Fedora user base; NVDA (Windows) has +the largest user base; VoiceOver (macOS) is required for Apple +accessibility compliance. + +''''' + +=== References + +* WCAG 2.3: https://www.w3.org/TR/WCAG23/ +* polyglot-i18n + LOL: https://github.com/hyperpolymath/polyglot-i18n +* Zotero Web API v3: https://www.zotero.org/support/dev/web_api/v3/start +* Zotero Local API: +https://www.zotero.org/support/dev/client_coding/connector_http_server +* Pandoc: https://pandoc.org/ +* Nougat (Meta): https://github.com/facebookresearch/nougat +* axe-core: https://github.com/dequelabs/axe-core +* Companion docs: +** `+DESIGN-2026-02-28-echidna-proof-ux.md+` +** `+DESIGN-2026-02-28-discipline-layouts.md+` +** `+DESIGN-2026-02-28-collaboration.md+` +** `+DESIGN-2026-02-28-slm-heutagogy.md+` diff --git a/docs/design/DESIGN-2026-02-28-infrastructure-requirements.md b/docs/design/DESIGN-2026-02-28-infrastructure-requirements.md deleted file mode 100644 index c8496025..00000000 --- a/docs/design/DESIGN-2026-02-28-infrastructure-requirements.md +++ /dev/null @@ -1,515 +0,0 @@ -# DESIGN: PanLL Infrastructure Requirements — Accessibility, i18n, Interoperability - -**Date:** 2026-02-28 -**Repo:** panll -**Author:** Jonathan D.A. Jewell -**Status:** Architectural requirements (binding on all future implementation) - -## Context - -PanLL is a workbench for formal methods, database design, language design, and -protocol engineering. These disciplines are inherently international, academic, and -collaborative. The tool must be accessible, translatable, and interoperable with the -research ecosystem from the start — not as afterthoughts. - -This document establishes infrastructure requirements that apply across all features -and all discipline layouts. These are not "nice to haves" — they are architectural -constraints. - -## Design Questions (from session dialogue) - -> "Can we add interoperability with Zotero and also make sure it has the full suite -> of accessibility features across the board, and stuff that is going to support -> Pandoc, agrep, internationalisation, OCR and so on in its design?" - ---- - -## 1. Accessibility (WCAG 2.3 — Binding Commitment) - -### Target Conformance - -| Level | Commitment | Notes | -|-------|------------|-------------------------------------------------| -| A | Mandatory | Every feature must pass before merge | -| AA | Target | Default standard for all new work | -| AAA | Best-effort| Where achievable without hampering functionality | - -**Trustfile implication:** The PanLL Trustfile (when created) must declare WCAG 2.3 AA -as the accessibility commitment. CI should enforce automated checks. - -### Requirements by Category - -#### Perceivable (WCAG Principle 1) - -| Requirement | WCAG | PanLL Application | -|------------------------------|---------|----------------------------------------------| -| Text alternatives | 1.1.1 A | All icons, glyphs, proof pipeline stages | -| Captions for audio | 1.2.2 A | Voice collaboration transcription | -| Audio description | 1.2.5 AA| Proof pipeline state narration | -| Colour not sole indicator | 1.4.1 A | Green/amber/red + icons + text labels | -| Contrast ratio 4.5:1 | 1.4.3 AA| All text including proof notation | -| Contrast ratio 3:1 (large) | 1.4.3 AA| Headers, block labels, toolbar buttons | -| Resize to 200% | 1.4.4 AA| All panes reflow without horizontal scroll | -| Reflow at 400% | 1.4.10 AA| Single-column layout at 400% zoom | -| Text spacing adjustable | 1.4.12 AA| No clipping when line-height/spacing changed | -| Non-text contrast 3:1 | 1.4.11 AA| Pipeline connectors, block borders, charts | - -**Proof pipeline specifics:** -- Green/amber/red stages must ALSO show: checkmark/clock/cross icons -- Screen reader: "Goal 1: solved. Goal 2: in progress. Goal 3: pending." -- Logical symbols (∀, ∃, →) must have aria-labels ("for all", "there exists", - "implies") -- Drift heatmap must have text-mode alternative (table of values) - -#### Operable (WCAG Principle 2) - -| Requirement | WCAG | PanLL Application | -|------------------------------|----------|---------------------------------------------| -| Keyboard accessible | 2.1.1 A | Every feature usable without mouse | -| No keyboard traps | 2.1.2 A | Escape always exits modals/menus | -| Focus order logical | 2.4.3 A | Tab order follows pane flow (L → N → W) | -| Focus visible | 2.4.7 AA | 2px solid outline on focused elements | -| Skip to content | 2.4.1 A | Skip links for each pane | -| Pointer cancellation | 2.5.2 A | Drag-drop has up-event cancellation | -| Dragging alternative | 2.5.7 AA | Block palette: keyboard select + Enter | -| Timing adjustable | 2.2.1 A | No auto-dismiss toasts; user controls timing | -| Reduced motion | 2.3.3 AAA| Respect `prefers-reduced-motion` | - -**Proof pipeline specifics:** -- Arrow keys navigate between pipeline stages -- Enter applies selected tactic or expands goal details -- Tab moves between the palette, pipeline, and goal display -- Drag-and-drop blocks have keyboard alternative: select block with Enter, Tab to - target stage, Enter to place -- The Blockly-style palette is navigable with arrow keys (category → block → apply) - -#### Understandable (WCAG Principle 3) - -| Requirement | WCAG | PanLL Application | -|------------------------------|----------|---------------------------------------------| -| Language of page | 3.1.1 A | `lang` attribute on root element | -| Language of parts | 3.1.2 AA | Proof notation in `lang="x-math"` | -| On focus no change | 3.2.1 A | Layout switching requires explicit action | -| Consistent navigation | 3.2.3 AA | Toolbar position stable across layouts | -| Error identification | 3.3.1 A | Proof errors identified in text, not colour | -| Error suggestion | 3.3.3 AA | Linter suggests corrections with description | -| Labels or instructions | 3.3.2 A | Goal input, tactic input, query input | - -#### Robust (WCAG Principle 4) - -| Requirement | WCAG | PanLL Application | -|------------------------------|----------|---------------------------------------------| -| Valid HTML | 4.1.1 A | Clean semantic HTML from Tea_Html | -| Name, role, value | 4.1.2 A | ARIA roles on all custom widgets | -| Status messages | 4.1.3 AA | `aria-live` for proof state changes | - -### Implementation Approach - -**Existing foundation:** Tea_Vdom already has 10 ARIA attribute functions. These -must be used consistently across ALL components — the gap between "functions exist" -and "functions are applied" must be closed. - -**Testing:** -- Automated: axe-core via Playwright in CI (catches ~30-40% of issues) -- Manual: screen reader testing with NVDA (Windows), Orca (Linux), VoiceOver (macOS) -- Keyboard: every feature must be testable with keyboard-only navigation - -**CSS requirements:** -```css -@media (prefers-reduced-motion: reduce) { - *, *::before, *::after { - animation-duration: 0.001ms !important; - transition-duration: 0.001ms !important; - } -} - -@media (prefers-contrast: more) { - :root { - --border-width: 2px; - --focus-outline: 3px solid; - } -} - -@media (prefers-color-scheme: dark) { - /* dark mode variables */ -} -``` - ---- - -## 2. Internationalisation (i18n) - -### Current State - -META.scm documents: English-only for v0.x, i18n framework planned for v1.0, -RTL support as future work. - -### Architecture - -**Framework:** polyglot-i18n + LOL (Localisation Overlay Language) - -Why polyglot-i18n + LOL over Project Fluent/gettext/ICU: -- Hyperpolymath-native i18n stack — dogfooded across the estate -- LOL handles plurals, gender, and grammatical cases cleanly -- polyglot-i18n provides the runtime loader and locale resolution -- ReScript integration via the polyglot-i18n ReScript bindings -- No dependency on Mozilla's `@fluent/bundle` npm package - -**File structure:** -``` -locales/ -├── en/ # English (source) -│ ├── app.lol # Core UI strings -│ ├── proofs.lol # Proof-specific terminology -│ ├── database.lol # Database-specific terminology -│ ├── protocols.lol # Protocol-specific terminology -│ └── accessibility.lol # Screen reader announcements -├── fr/ -├── de/ -├── ja/ -├── ar/ # RTL -├── zh-Hans/ -└── ... -``` - -**Example LOL file (`locales/en/proofs.lol`):** -``` -proof-goal-solved = Goal { $number } solved -proof-goals-remaining = { $count -> - [one] { $count } goal remaining - *[other] { $count } goals remaining -} -proof-status-success = Proof complete — all goals discharged -proof-status-failed = Proof failed at goal { $goal } -tactic-suggestion = Suggested tactic: { $name } (confidence { $confidence }) -``` - -**Localisation of mathematical notation:** Mathematical symbols (∀, ∃, →, ∧, ∨) are -universal and do NOT get translated. But their spoken/screen-reader forms DO: - -| Symbol | English | French | German | -|--------|------------------|-------------------|-------------------| -| ∀ | for all | pour tout | für alle | -| ∃ | there exists | il existe | es existiert | -| → | implies | implique | impliziert | -| ∧ | and | et | und | -| ∨ | or | ou | oder | - -### RTL Support - -Arabic, Hebrew, Farsi, Urdu require right-to-left layout. Critically, mixed-direction -content is common in proofs (RTL prose + LTR mathematical notation): - -```html -
- - نثبت أن ∀ n : ℕ, n + 0 = n - -
-``` - -PanLL's pane system must handle `dir="rtl"` on the root and use logical CSS -properties (`inline-start`/`inline-end` instead of `left`/`right`). - ---- - -## 3. Zotero Integration - -### Why Zotero - -Proofs cite papers. Database schemas reference standards. Protocols reference RFCs. -Zotero is the dominant open-source reference manager in academia. Integration means -users don't need to leave PanLL to find or cite a reference. - -### Integration Points - -| Feature | Mechanism | Notes | -|--------------------------|------------------------------|-----------------------------| -| Search user's library | Zotero Web API (v3) | Read-only, API key auth | -| Insert citation | CSL-JSON → formatted cite | Into proof comments/docs | -| Link theorem to paper | Attach Zotero item key | "This lemma from [Smith24]" | -| Browse collections | Zotero API `/collections` | Filtered by discipline | -| Export bibliography | CSL-JSON → Pandoc → BibTeX | For paper writing | -| Local Zotero (optional) | Zotero local API (port 23119)| No cloud dependency | - -### Zotero API Details - -**Authentication:** API key (per-user, stored in PanLL config) - -**Key endpoints:** - -``` -GET /users/{userId}/items?q={searchTerm} # Search library -GET /users/{userId}/items/{itemKey} # Get item details -GET /users/{userId}/collections # List collections -GET /users/{userId}/items/{itemKey}/children # Attachments (PDFs) -``` - -**CSL-JSON** is the interchange format — Zotero exports it, Pandoc consumes it, -and PanLL can render formatted citations from it. - -### Local-First Design - -Zotero 7 exposes a local HTTP API on port 23119 (when Zotero is running). PanLL -should prefer the local API (no network dependency, faster) and fall back to the -web API. This aligns with PanLL's offline-first principle. - -``` -1. Try localhost:23119 (Zotero desktop running locally) -2. Fall back to api.zotero.org (cloud, requires API key) -3. Fall back to manual BibTeX/CSL-JSON file import -``` - ---- - -## 4. Pandoc Integration - -### Why Pandoc - -PanLL produces proof scripts, design documents, query results, protocol specs. These -need to be exportable in multiple formats for papers, reports, presentations, and -archival. Pandoc is the universal document converter. - -### Export Targets - -| Format | Use Case | -|--------------|---------------------------------------------| -| LaTeX/PDF | Academic papers, proof appendices | -| HTML | Web publishing, sharing | -| Markdown | GitHub/GitLab documentation | -| AsciiDoc | RSR documentation standard | -| DOCX | Collaboration with Word users | -| EPUB | Long-form documentation | -| Typst | Modern alternative to LaTeX | -| Djot | Lightweight markup (hyperpolymath standard) | - -### Integration Approach - -**Pandoc as Tauri sidecar or Deno subprocess:** - -``` -PanLL proof script / document - │ - ▼ - Internal representation (Pandoc AST JSON) - │ - ▼ - pandoc --from json --to {format} --citeproc --bibliography refs.json - │ - ▼ - Output file (PDF, HTML, DOCX, etc.) -``` - -**`--citeproc`** handles Zotero citations automatically — CSL-JSON from Zotero → -Pandoc citeproc → formatted bibliography in output. - -**Custom Pandoc filters** (Lua) for PanLL-specific content: -- Proof pipeline → LaTeX `proof` environment -- Tactic sequences → `lstlisting` with Coq/Lean syntax -- Trust level badges → coloured boxes in PDF -- ECHIDNA dispatch results → formatted tables - -### Pandoc AST as Intermediate Representation - -Rather than building format-specific exporters for each output type, PanLL should -produce Pandoc AST JSON as its universal export format. This means: -- One export path, many output formats -- New formats added by installing Pandoc writers (no PanLL code changes) -- Community can write custom Pandoc filters for domain-specific rendering - ---- - -## 5. Fuzzy Search (agrep / Approximate Matching) - -### Why Fuzzy Search - -Users mistype tactic names. Theorem names are long and easy to get wrong. -Database entity names have variations. Protocol state names may be remembered -imprecisely. Exact search fails silently; fuzzy search finds what you meant. - -**Accessibility connection:** Users with motor impairments, dyslexia, or who are -typing in a non-native language benefit enormously from approximate matching. - -### Implementation - -**Algorithm:** Levenshtein distance with BK-tree index for fast lookup - -**Where fuzzy search applies:** - -| Context | Search corpus | Threshold | -|------------------------|----------------------------|-----------| -| Tactic name input | Prover's tactic catalog | Edit distance ≤ 2 | -| Theorem search | Mathlib / theorem corpus | Edit distance ≤ 3 | -| Entity name lookup | VeriSimDB entity list | Edit distance ≤ 2 | -| Protocol state search | State machine state names | Edit distance ≤ 2 | -| Command palette | All PanLL commands | Subsequence match | - -**Behaviour:** -``` -User types: "inducton" -Fuzzy match: "induction" (distance 1) -UI shows: "induction" with subtle correction indicator - -User types: "Nat.add_como" -Fuzzy match: "Nat.add_comm" (distance 2) -UI shows: "Did you mean Nat.add_comm?" -``` - -**ReScript implementation:** Pure ReScript Levenshtein function (~30 lines). No -external dependency needed for the core algorithm. For large corpora (Mathlib's -100k+ theorems), a BK-tree or trigram index for sub-millisecond lookup. - ---- - -## 6. OCR (Optical Character Recognition) - -### Why OCR - -Researchers work with papers (PDF), textbooks (scanned), handwritten notes -(whiteboard photos), and legacy documents. Importing proof goals, theorem -statements, or protocol specs from these sources should be seamless. - -**Mathematical OCR** is a specific sub-problem — standard OCR (Tesseract) handles -prose well but struggles with mathematical notation. Specialised tools exist. - -### Integration Approach - -| Source | Tool | Output | -|------------------|-----------------------------|----------------------| -| PDF (digital) | Pandoc / pdftotext | Structured text | -| PDF (scanned) | Tesseract OCR + layout | Raw text + positions | -| Mathematical | Mathpix / InftyReader / Nougat | LaTeX notation | -| Handwritten | Mathpix or MyScript | LaTeX notation | -| Whiteboard photo | Tesseract + preprocessing | Raw text | - -**Workflow:** -``` -1. User imports image/PDF into PanLL (drag-drop or file picker) -2. PanLL detects content type (prose, math, mixed) -3. For math: send to math-OCR engine → LaTeX output -4. Convert LaTeX to PanLL-Universal or prover syntax -5. User reviews and corrects in the syntax editor -6. Corrected text becomes proof goal or constraint -``` - -**Local-first:** Tesseract runs locally (no cloud dependency). For mathematical OCR, -Nougat (Meta's open-source scientific document OCR) runs locally on GPU. Mathpix is -cloud-based and optional. - -**Accessibility note:** OCR also enables PanLL to describe images to screen reader -users — "This image contains the formula: for all n, n + 0 = n." - ---- - -## 7. Cross-Cutting Concerns - -### Offline-First Principle - -Every feature in this document must work offline except where network access is -inherently required: - -| Feature | Offline? | Notes | -|------------------|-----------|-----------------------------------------| -| Accessibility | Yes | Fully local | -| i18n | Yes | Locale files bundled | -| Zotero (local) | Yes | localhost:23119 | -| Zotero (cloud) | No | Requires api.zotero.org | -| Pandoc export | Yes | Pandoc binary bundled or local install | -| Fuzzy search | Yes | Pure ReScript, no network | -| OCR (Tesseract) | Yes | Local binary | -| OCR (Nougat) | Yes | Local model | -| OCR (Mathpix) | No | Cloud API | -| Collaboration | No | Requires Phoenix server | - -### Trustfile Obligations - -When the PanLL Trustfile is created, it must declare: - -``` -(accessibility - (standard "WCAG 2.3") - (conformance-level "AA") - (target-level "AAA where feasible") - (testing "automated axe-core + manual screen reader") - (policy "no feature ships without A compliance")) - -(internationalisation - (framework "polyglot-i18n + LOL") - (source-language "en") - (rtl-support "planned v1.0") - (math-notation "universal, not translated")) - -(interoperability - (citation-manager "Zotero API v3 + local API") - (document-export "Pandoc AST JSON") - (search "fuzzy Levenshtein, edit distance ≤ 3") - (ocr "Tesseract local + Nougat for math")) -``` - -### Performance Budget - -Infrastructure features must not degrade the core experience: - -| Feature | Budget | -|------------------|-------------------------------| -| Fuzzy search | < 10ms for 10k-item corpus | -| i18n string lookup| < 1ms per string | -| ARIA attribute render | negligible (HTML attrs) | -| Pandoc export | < 5s for typical proof doc | -| OCR | < 30s for a page of math | -| Zotero search | < 2s (local), < 5s (cloud) | - ---- - -## Implementation Priority - -| Feature | Priority | Phase | Dependency | -|------------------|----------|--------------|-----------------------| -| ARIA pass (close gap) | P0 | Immediate | Existing components | -| `prefers-reduced-motion` | P0 | Immediate | CSS only | -| `prefers-contrast` | P0 | Immediate | CSS only | -| Keyboard navigation audit | P0 | Immediate | Existing components | -| Fuzzy search | P1 | Next sprint | Pure ReScript | -| Pandoc export | P1 | Next sprint | Pandoc binary | -| polyglot-i18n + LOL setup| P2 | v1.0 prep | polyglot-i18n bindings| -| Zotero local API | P2 | v1.0 prep | HTTP client | -| OCR (Tesseract) | P3 | v1.0+ | Tesseract binary | -| OCR (math/Nougat)| P3 | v1.0+ | GPU, model download | -| RTL layout | P3 | v1.0+ | LOL + CSS logical | - ---- - -## Open Questions - -1. **Should PanLL bundle Pandoc, or require it as a system dependency?** Bundling adds - ~80 MB to the Tauri binary but eliminates "install Pandoc first" friction. - -2. **Should fuzzy search be a standalone ReScript module publishable to the ecosystem?** - Other hyperpolymath tools (ReScript Evangeliser, NQC) could use it. - -3. **Is Nougat (Meta's math OCR) the right choice, or should we wait for better open - models?** Nougat is good but requires a GPU for reasonable speed. - -4. **Should Zotero integration be a PanLL core feature or a plugin?** Core means - everyone gets it; plugin means non-academics don't pay the code size cost. - -5. **Which screen readers should be the primary test targets?** Orca (Linux) is - most relevant for the Fedora user base; NVDA (Windows) has the largest user base; - VoiceOver (macOS) is required for Apple accessibility compliance. - ---- - -## References - -- WCAG 2.3: https://www.w3.org/TR/WCAG23/ -- polyglot-i18n + LOL: https://github.com/hyperpolymath/polyglot-i18n -- Zotero Web API v3: https://www.zotero.org/support/dev/web_api/v3/start -- Zotero Local API: https://www.zotero.org/support/dev/client_coding/connector_http_server -- Pandoc: https://pandoc.org/ -- Nougat (Meta): https://github.com/facebookresearch/nougat -- axe-core: https://github.com/dequelabs/axe-core -- Companion docs: - - `DESIGN-2026-02-28-echidna-proof-ux.md` - - `DESIGN-2026-02-28-discipline-layouts.md` - - `DESIGN-2026-02-28-collaboration.md` - - `DESIGN-2026-02-28-slm-heutagogy.md` diff --git a/docs/design/DESIGN-2026-02-28-slm-heutagogy.adoc b/docs/design/DESIGN-2026-02-28-slm-heutagogy.adoc new file mode 100644 index 00000000..a33ab33c --- /dev/null +++ b/docs/design/DESIGN-2026-02-28-slm-heutagogy.adoc @@ -0,0 +1,604 @@ +== DESIGN: Prover-Directed SLM Heutagogy — Learning to Reason from Formal Verification + +*Date:* 2026-02-28 *Repo:* panll *Author:* Jonathan D.A. Jewell +*Status:* Research design (theoretical + practical exploration) + +=== Context + +PanLL’s ECHIDNA integration provides a formal proof engine that can +unambiguously judge whether a proof step is correct. Most ML training +signals are noisy — human labels disagree, reward functions are +approximate, loss landscapes are deceptive. But a proof either +type-checks or it doesn’t. This is a _perfect_ training signal. + +The question is: can we use this perfect signal to teach an SLM to +reason better, not just about proofs, but about reasoning itself? + +=== Design Questions (from session dialogue) + +____ +"`Imagine that I decided to use my SLM with the proofer… could I get the +proofer to actually train the SLM by SLM-directed heutagogy? Does this +exist, and does what I am saying make sense?`" +____ + +____ +"`It would literally learn from the logic and the proofs the rights and +wrongs of its reasoning, in the same way we would see it.`" +____ + +____ +"`As an SLM it would not be '`state locked`' as an entity. If we can +find a way to tether part of it, in maybe a two layer system, could we +additionally get it to develop its understanding overnight, etc. for +particular domains?`" +____ + +____ +"`Perhaps with support from things like DeepProbLog.`" +____ + +''''' + +=== Why This Works (The Core Insight) + +The user’s insight is precise: *formal verification provides a lossless +supervision signal for training a reasoning system.* + +Compare to other ML training regimes: + +[width="100%",cols="36%,32%,32%",options="header",] +|=== +|Training regime |Signal quality |Signal source +|Human labelling (RLHF) |Noisy, subjective, expensive |Annotators +disagree + +|Self-supervised (next token) |Abundant but indirect |Correlation ≠ +reasoning + +|Reward models |Approximate, can be gamed |Learned proxy of human +preference + +|Unit tests (code gen) |Binary but incomplete |Tests don’t cover all +cases + +|*Formal proof checking* |*Perfect, complete, unforgeable* +|*Mathematical truth* +|=== + +When the SLM suggests `+induction n+` and Coq says "`proof complete`", +that is an absolute ground truth. When it suggests `+ring+` and Coq says +"`this tactic failed`", that is an absolute ground truth. There is no +label noise. There is no reward hacking. The prover is an incorruptible +teacher. + +This is the cleanest reinforcement signal in all of machine learning. + +''''' + +=== What Exists Today + +==== Close Predecessors + +*AlphaProof (DeepMind, 2024):* - Reinforcement learning + formal +verification (Lean 4) for competition mathematics - Solved 4/6 IMO 2024 +problems at silver medal level - Uses a large model, not an SLM; not +self-directed - Proves the concept: prover-as-training-signal works at +the frontier + +*HTPS — Hyper-Tree Proof Search (Meta, 2022):* - Online learning during +proof search — the model improves as it searches - Each +successful/failed proof branch updates the policy - Closest to +"`learning from the prover in real-time`" - But not self-directed; fixed +curriculum + +*ReProver / LeanDojo (2023):* - Retrieval-augmented theorem proving in +Lean - Trains on Mathlib proofs, retrieves relevant premises - Shows +that small specialised models can outperform large general ones on +proofs + +*Draft, Sketch, Prove (2023):* - LLM drafts informal proof → translator +converts to formal → verifier checks - Failed proofs are discarded, not +learned from - Missing the heutagogic loop + +*LEGO-Prover (2024):* - LLM grows a verified lemma library over time - +Each proved lemma becomes available for future proofs - Closest to +"`developing understanding over time`" - But the model weights don’t +update; only the lemma library grows + +==== Neural-Symbolic Integration + +*DeepProbLog (KU Leuven, 2018-present):* - Integrates neural networks +with ProbLog (probabilistic logic programming) - Neural predicates: +neural network outputs become logic atoms - Training: backpropagates +through the logic program into the neural network - *Key capability:* +The logic constrains what the neural network can learn - Directly +relevant: could provide the "`tethered`" logical layer + +*NeurASP (2020):* - Answer Set Programming + neural networks - Logic +rules constrain neural network training - Can learn from logical +inconsistencies (not just proof success/failure) + +*Logic Tensor Networks (LTN, 2022):* - First-order logic with +real-valued semantics - Logical axioms become differentiable loss +functions - "`Satisfying the axioms`" = training the neural network + +*Scallop (2023):* - Differentiable Datalog — backpropagates through +logical reasoning - Provenance tracking enables gradient computation +through logical inference - Could provide the "`how did this proof step +contribute?`" signal + +==== What Does NOT Exist (The Gap) + +No system currently combines all of these: + +[arabic] +. ✅ Prover as training signal (AlphaProof, HTPS) +. ✅ Small model that continues training (LoRA fine-tuning is routine) +. ✅ Neural-symbolic integration (DeepProbLog, NeurASP, LTN) +. ❌ *Self-directed curriculum* (the SLM chooses what to learn next) +. ❌ *Two-layer tethered architecture* (stable reasoning + plastic +adaptation) +. ❌ *Overnight autonomous training* against a prover +. ❌ *Domain-specific specialisation* that accumulates across sessions + +The user’s proposal fills this gap. It is novel but entirely feasible +given existing components. + +''''' + +=== Architecture: Two-Layer Tethered SLM + +==== The Problem with Vanilla Fine-Tuning + +If you fine-tune an SLM on proof data naively, you get catastrophic +forgetting — it learns new tactics but forgets how to parse goals. If +you freeze it entirely, it can’t learn at all. The user’s intuition +about a "`two-layer system where part is tethered`" maps precisely to a +known solution. + +==== Complementary Learning Systems (CLS) Architecture + +Inspired by how the human brain learns: the hippocampus learns quickly +(one-shot, today’s proofs) while the neocortex consolidates slowly +(overnight, generalised patterns). This maps to: + +.... +┌─────────────────────────────────────────────────────────┐ +│ SLM Architecture │ +│ │ +│ ┌───────────────────────────────────────────────────┐ │ +│ │ Layer 1: TETHERED BASE (frozen weights) │ │ +│ │ │ │ +│ │ • Pre-trained language understanding │ │ +│ │ • Syntax parsing for Coq/Lean/SMT-LIB/etc. │ │ +│ │ • Basic logical reasoning patterns │ │ +│ │ • Natural language comprehension │ │ +│ │ │ │ +│ │ This layer NEVER changes. It provides stable │ │ +│ │ foundations that domain learning builds upon. │ │ +│ │ │ │ +│ │ Implementation: frozen base model weights │ │ +│ └───────────────────────────┬───────────────────────┘ │ +│ │ │ +│ ┌───────────────────────────▼───────────────────────┐ │ +│ │ Layer 2: PLASTIC ADAPTER (trainable LoRA) │ │ +│ │ │ │ +│ │ • Domain-specific tactic preferences │ │ +│ │ • Proof pattern recognition for THIS domain │ │ +│ │ • Learned heuristics from past proof attempts │ │ +│ │ • User-specific style adaptation │ │ +│ │ │ │ +│ │ This layer updates continuously from proof │ │ +│ │ feedback. Multiple adapters can coexist for │ │ +│ │ different domains (one for algebra, one for │ │ +│ │ protocol verification, one for type theory). │ │ +│ │ │ │ +│ │ Implementation: LoRA adapters (rank 8-16) │ │ +│ │ Storage: ~10-50 MB per domain adapter │ │ +│ └──────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────┘ +.... + +*Why LoRA is the right mechanism:* - Adapter weights are small (10-50 MB +vs. gigabytes for full model) - Multiple adapters can be swapped in/out +for different domains - Training is fast (minutes, not hours) - The base +model is never modified — stability is guaranteed - Well-understood, +battle-tested technique + +==== The Heutagogic Loop + +Heutagogy = self-determined learning. The SLM doesn’t just learn from +proofs it’s asked to do — it decides what to learn next, based on where +it’s weakest. + +.... +┌──────────────────────────────────────────────────────────────┐ +│ Heutagogic Training Loop │ +│ │ +│ 1. SLM examines its own performance history │ +│ "I failed 7/10 induction proofs on lists but │ +│ succeeded 9/10 on natural numbers" │ +│ │ +│ 2. SLM selects training curriculum │ +│ "I should practice list induction tonight" │ +│ → Generates or selects proof goals from a library │ +│ │ +│ 3. SLM attempts proofs against ECHIDNA │ +│ → Tries tactics on the selected goals │ +│ → ECHIDNA returns success/failure for each step │ +│ │ +│ 4. SLM trains on results │ +│ → Successful proof traces become positive examples │ +│ → Failed attempts with prover diagnostics become │ +│ negative examples with correction signal │ +│ │ +│ 5. SLM evaluates improvement │ +│ → Re-attempts previously failed proofs │ +│ → If improved, moves to next weakness │ +│ → If stuck, escalates difficulty or tries new approach │ +│ │ +│ 6. Loop continues until budget exhausted (time/compute) │ +│ or target proficiency reached │ +│ │ +└──────────────────────────────────────────────────────────────┘ +.... + +*The curriculum is self-directed because:* - The SLM tracks its own +success/failure rates per tactic, per domain, per goal type - It +prioritises areas where it’s weakest (exploration) or where small gains +would unlock the most downstream proofs (exploitation) - It can generate +its own training goals by mutating existing theorems (e.g., "`if I +proved n + 0 = n, can I prove n * 1 = n?`") - It can request harder +variants of goals it’s already mastered + +==== Overnight Training Protocol + +.... +┌──────────────────────────────────────────────────────────────┐ +│ OVERNIGHT TRAINING SCHEDULE (example) │ +│ │ +│ 22:00 SLM reviews today's proof sessions │ +│ → Identifies 12 failed tactic applications │ +│ → Clusters failures by type (3 induction, 4 rewrite, │ +│ 2 automation, 3 unfolding) │ +│ │ +│ 22:15 SLM generates training curriculum │ +│ → Selects 50 list induction goals from Mathlib │ +│ → Selects 40 rewriting exercises │ +│ → Generates 20 novel goals by mutation │ +│ │ +│ 22:30 Training loop begins │ +│ - SLM attempts goals → ECHIDNA validates │ +│ 05:30 → LoRA adapter weights updated after each batch │ +│ → ~110 goals attempted, ~70 eventually proved │ +│ → Progress logged to training journal │ +│ │ +│ 05:30 Evaluation checkpoint │ +│ → Re-attempt today's 12 failures │ +│ → 8/12 now succeed (67% recovery rate) │ +│ → Adapter saved as domain-v{N+1} │ +│ │ +│ 06:00 Training report ready for user │ +│ "Overnight: +15% on list induction, │ +│ +8% on rewriting, 2 goals still stuck │ +│ (suggest manual inspection)" │ +└──────────────────────────────────────────────────────────────┘ +.... + +*Resource budget:* An SLM (1-3B params) with LoRA training on a modern +GPU uses ~4-8 GB VRAM and can process ~100 proof attempts per hour. +Overnight (8 hours) = ~800 proof attempts, which is substantial +curriculum coverage. + +*Without GPU:* CPU-only LoRA training is slower (~10-20 attempts/hour) +but still useful for focused domain training. A Threadripper or M-series +Mac can handle this comfortably overnight. + +''''' + +=== DeepProbLog Integration + +DeepProbLog provides something the pure LoRA approach doesn’t: *logical +constraints on what the SLM can learn.* + +==== How DeepProbLog Fits + +.... +┌──────────────────────────────────────────────────────────┐ +│ │ +│ ┌────────────┐ │ +│ │ SLM │──── tactic prediction ────┐ │ +│ │ (neural) │ │ │ +│ └────────────┘ ▼ │ +│ ▲ ┌─────────────────┐ │ +│ │ │ DeepProbLog │ │ +│ │ │ Logic Program │ │ +│ gradient │ │ │ +│ from logic │ • Type rules │ │ +│ │ │ • Tactic pre/ │ │ +│ │ │ postconditions│ │ +│ │ │ • Domain axioms │ │ +│ │ └────────┬────────┘ │ +│ │ │ │ +│ └───────────────────────────────────┘ │ +│ │ +│ Logic program constrains SLM training: │ +│ "If goal is ∀-quantified, intro is always valid" │ +│ "If goal is an equation, rewrite is relevant" │ +│ "induction requires a recursive type" │ +│ │ +└──────────────────────────────────────────────────────────┘ +.... + +*What DeepProbLog adds:* + +[arabic] +. *Logical pre/postconditions as training constraints:* Instead of just +"`this tactic succeeded/failed`", DeepProbLog encodes WHY a tactic is +applicable. The gradient flows through the logical rules into the SLM, +teaching it not just what works but the structure of why. +. *Probabilistic reasoning about tactic choice:* DeepProbLog naturally +handles uncertainty. "`induction is 80% likely to be the right tactic +here`" is a probabilistic logic statement, not just a neural confidence +score. +. *Compositional learning:* Logical rules compose. If the SLM learns +that "`intro works on ∀-goals`" and "`induction works on nat-typed +variables`", it can compose these to predict "`intro then induction`" on +"`∀ n : nat, …`" without having seen that specific combination. +. *Explainability:* The logical program provides a human-readable +explanation of why the SLM made a prediction. "`I chose induction +because: (a) the goal contains a recursive type (nat), (b) the goal is +universally quantified, (c) my experience with similar goals shows 87% +success rate.`" + +==== ProbLog Rules (Example) + +[source,prolog] +---- +% Neural predicate: SLM predicts tactic relevance +nn(tactic_net, [GoalType, GoalShape, Context], Tactic) :: tactic_relevant(Goal, Tactic). + +% Logical constraints (these constrain what the SLM can learn) +valid_tactic(Goal, intro) :- + goal_has_forall(Goal). + +valid_tactic(Goal, induction(Var)) :- + goal_has_forall(Goal), + variable_has_recursive_type(Var). + +valid_tactic(Goal, rewrite(Lemma)) :- + goal_is_equation(Goal), + lemma_matches_lhs(Lemma, Goal). + +% Combined: SLM prediction + logical validity +suggested_tactic(Goal, Tactic) :- + tactic_relevant(Goal, Tactic), + valid_tactic(Goal, Tactic). + +% Training signal: prover confirms or denies +proof_step_correct(Goal, Tactic) :- + suggested_tactic(Goal, Tactic), + echidna_validates(Goal, Tactic). +---- + +The key: `+tactic_relevant+` is a neural predicate (the SLM’s output), +but `+valid_tactic+` is a logical constraint. DeepProbLog trains the SLM +to satisfy BOTH — it must predict tactics that are both neurally +relevant AND logically valid. This prevents the SLM from learning +spurious correlations. + +''''' + +=== Risks and Mitigations + +[width="100%",cols="23%,35%,42%",options="header",] +|=== +|Risk |Severity |Mitigation +|SLM overfits to training domain |Medium |Multiple LoRA adapters per +domain; regularly evaluate on out-of-domain goals + +|Catastrophic forgetting in adapter |Low |LoRA rank is small; forgetting +is bounded. Periodic adapter checkpoints allow rollback + +|Overnight training runs up compute costs |Low |SLM is small (1-3B); +LoRA training is efficient; runs on local hardware + +|SLM learns wrong generalisations from limited proofs |Medium +|DeepProbLog’s logical constraints prevent logically invalid +generalisations + +|Training loop diverges (gets worse, not better) |Medium |Evaluation +checkpoints every N goals; auto-stop if accuracy drops below baseline + +|User trusts SLM too much after overnight improvement |Medium |Trust +display always shows ECHIDNA’s verification, not SLM’s confidence; SLM +is advisor, not oracle + +|Security: SLM training data leakage |Low |Training is local, no data +leaves the machine; adapters can be encrypted at rest +|=== + +==== The Fundamental Safety Property + +*The prover is always the final authority.* No matter how much the SLM +learns, its output is always validated against ECHIDNA before being +presented to the user as correct. The SLM can become arbitrarily good at +suggesting tactics, but it can never claim a proof is valid — only the +prover can do that. + +This is structurally different from LLM code generation, where the +model’s output is executed directly. Here, the model’s output is checked +against mathematical truth before execution. The worst case of a +badly-trained SLM is bad suggestions, not incorrect proofs. + +''''' + +=== Beyond Proofs: Reasoning Transfer + +The most speculative but most exciting possibility: *an SLM trained on +formal proofs might reason better about everything.* + +Formal proofs teach: - *Logical structure:* Premises → conclusions, case +analysis, contradiction - *Precision:* Every step must be justified; no +hand-waving - *Abstraction:* Recognising when two problems have the same +structure - *Strategy:* When to try induction vs. case split +vs. automation + +These are not proof-specific skills. They are general reasoning skills. +An SLM that has internalised "`when I see a recursive structure, +consider induction`" from thousands of proof attempts may apply that +pattern to non-proof reasoning: "`this data structure is recursive, so +the algorithm should be recursive too.`" + +This is speculative but testable. A concrete experiment: train an SLM on +10,000 Coq proofs overnight, then evaluate it on non-proof reasoning +benchmarks (ARC, GSM8K, LogiQA). If scores improve, the proof training +is teaching general reasoning. If scores don’t change, the learning is +domain-specific (still valuable, just narrower). + +''''' + +=== Comparison to Existing Approaches + +[width="100%",cols="12%,^24%,^18%,^13%,^13%,^20%",options="header",] +|=== +|System |Learns from proofs? |Self-directed? |Two-layer? |Overnight? +|Neural-symbolic? +|AlphaProof |Yes |No (fixed curriculum) |No |No (massive cluster) |No + +|HTPS |Yes (online) |No |No |No |No + +|ReProver |Yes (offline) |No |No |No |No + +|LEGO-Prover |Yes (library only) |Partially |No |No |No + +|DeepProbLog |Not proofs specifically |No |Partially |No |Yes + +|*PanLL SLM* |*Yes* |*Yes (heutagogy)* |*Yes (LoRA)* |*Yes* |*Yes +(DeepProbLog)* +|=== + +Each component exists in isolation and is well-established. PanLL’s +contribution is not invention but integration — pulling these into a +single coherent workspace so the user doesn’t need 30 windows open. The +combination is uncommon, but every individual piece is proven +technology. The value is the unified experience, not any single +component. + +''''' + +=== Implementation Phases + +==== Phase A: Proof Replay Training (batch, no heutagogy) + +* [ ] Collect proof traces from ECHIDNA sessions (successful and failed) +* [ ] Format as SLM training data (goal, context, tactic, outcome) +* [ ] LoRA fine-tune on collected traces +* [ ] Evaluate: does the adapter improve tactic suggestion accuracy? + +==== Phase B: Online Learning (real-time, no self-direction) + +* [ ] After each ECHIDNA validation, update adapter weights +* [ ] Implement replay buffer to prevent catastrophic forgetting +* [ ] Checkpoint adapter after each session + +==== Phase C: Self-Directed Curriculum (heutagogy) + +* [ ] SLM tracks success/failure rates per tactic + domain +* [ ] Curriculum selector: choose goals that target weakest areas +* [ ] Goal mutation: generate new goals from proved theorems +* [ ] Overnight training scheduler with evaluation checkpoints + +==== Phase D: DeepProbLog Integration + +* [ ] Define logical tactic preconditions in ProbLog +* [ ] Wire SLM as neural predicate in DeepProbLog +* [ ] Train through combined neural-symbolic pipeline +* [ ] Evaluate: does logical constraint improve learning efficiency? + +==== Phase E: Multi-Domain Adapters + +* [ ] Separate LoRA adapters per domain (algebra, lists, protocols, +types) +* [ ] Adapter registry with metadata (domain, training history, +accuracy) +* [ ] Auto-select adapter based on current proof context +* [ ] Cross-domain transfer experiments + +''''' + +=== Open Questions + +[arabic] +. *Which SLM base model?* Candidates: Phi-3-mini (3.8B), Gemma-2-2B, +Qwen2.5-1.5B, CodeGemma-2B. Need: good code understanding, small enough +for local LoRA training, permissive license. +. *How much proof data is needed for meaningful adapter improvement?* +Hypothesis: 50-100 successful proofs per domain gives measurable +improvement. Testable. +. *Should the SLM train on the full proof trace or just tactic-outcome +pairs?* Full traces give richer signal but are more expensive to +process. +. *Can the heutagogic curriculum be itself learned?* Meta-learning: +train a small policy network that decides what the SLM should study +next, based on improvement rates across domains. +. *What is the right LoRA rank for proof domain adaptation?* Too low +(2-4) may underfit; too high (32-64) may overfit. Likely sweet spot: +8-16. +. *How does this interact with PanLL’s trust display?* The trust level +should distinguish "`SLM suggested this`" (advisory) from "`ECHIDNA +verified this`" (ground truth). The SLM’s confidence and the prover’s +verdict are independent signals. +. *Is DeepProbLog the right neural-symbolic framework?* Alternatives: +NeurASP (answer set programming), Scallop (differentiable Datalog), LTN +(logic tensor networks). DeepProbLog has the best probabilistic +semantics but Scallop may be faster for large-scale training. + +''''' + +=== References + +==== Theorem Proving with ML + +* Lample et al. (2022). "`HyperTree Proof Search for Neural Theorem +Proving.`" NeurIPS. +* Yang et al. (2023). "`LeanDojo: Theorem Proving with +Retrieval-Augmented Language Models.`" +* Jiang et al. (2023). "`Draft, Sketch, and Prove: Guiding Formal +Theorem Provers with Informal Proofs.`" +* Wang et al. (2024). "`LEGO-Prover: Neural Theorem Proving with Growing +Libraries.`" +* AlphaProof team (2024). "`AI achieves silver-medal standard solving +International Mathematical Olympiad problems.`" + +==== Neural-Symbolic Learning + +* Manhaeve et al. (2018). "`DeepProbLog: Neural Probabilistic Logic +Programming.`" NeurIPS. +* Yang et al. (2020). "`NeurASP: Embracing Neural Networks into Answer +Set Programming.`" +* Li et al. (2023). "`Scallop: A Language for Neurosymbolic +Programming.`" PLDI. +* Badreddine et al. (2022). "`Logic Tensor Networks.`" Artificial +Intelligence. + +==== Continual Learning + +* Hu et al. (2022). "`LoRA: Low-Rank Adaptation of Large Language +Models.`" ICLR. +* Kumaran et al. (2016). "`What Learning Systems do Intelligent Agents +Need? Complementary Learning Systems Theory Updated.`" Trends in +Cognitive Sciences. + +==== Self-Directed Learning + +* Hase & Kenyon (2000). "`From Andragogy to Heutagogy.`" UltiBASE. +* Schmidhuber (1991). "`Curious Model-Building Control Systems.`" IJCNN. + +==== Companion Design Documents + +* `+DESIGN-2026-02-28-echidna-proof-ux.md+` — Proof UX and SLM advisory +role +* `+DESIGN-2026-02-28-discipline-layouts.md+` — Domain-specific layouts +* `+DESIGN-2026-02-28-collaboration.md+` — Collaborative proof sessions diff --git a/docs/design/DESIGN-2026-02-28-slm-heutagogy.md b/docs/design/DESIGN-2026-02-28-slm-heutagogy.md deleted file mode 100644 index aaf09985..00000000 --- a/docs/design/DESIGN-2026-02-28-slm-heutagogy.md +++ /dev/null @@ -1,528 +0,0 @@ -# DESIGN: Prover-Directed SLM Heutagogy — Learning to Reason from Formal Verification - -**Date:** 2026-02-28 -**Repo:** panll -**Author:** Jonathan D.A. Jewell -**Status:** Research design (theoretical + practical exploration) - -## Context - -PanLL's ECHIDNA integration provides a formal proof engine that can unambiguously -judge whether a proof step is correct. Most ML training signals are noisy — human -labels disagree, reward functions are approximate, loss landscapes are deceptive. -But a proof either type-checks or it doesn't. This is a *perfect* training signal. - -The question is: can we use this perfect signal to teach an SLM to reason better, -not just about proofs, but about reasoning itself? - -## Design Questions (from session dialogue) - -> "Imagine that I decided to use my SLM with the proofer... could I get the proofer -> to actually train the SLM by SLM-directed heutagogy? Does this exist, and does -> what I am saying make sense?" - -> "It would literally learn from the logic and the proofs the rights and wrongs of -> its reasoning, in the same way we would see it." - -> "As an SLM it would not be 'state locked' as an entity. If we can find a way to -> tether part of it, in maybe a two layer system, could we additionally get it to -> develop its understanding overnight, etc. for particular domains?" - -> "Perhaps with support from things like DeepProbLog." - ---- - -## Why This Works (The Core Insight) - -The user's insight is precise: **formal verification provides a lossless supervision -signal for training a reasoning system.** - -Compare to other ML training regimes: - -| Training regime | Signal quality | Signal source | -|----------------|---------------|---------------| -| Human labelling (RLHF) | Noisy, subjective, expensive | Annotators disagree | -| Self-supervised (next token) | Abundant but indirect | Correlation ≠ reasoning | -| Reward models | Approximate, can be gamed | Learned proxy of human preference | -| Unit tests (code gen) | Binary but incomplete | Tests don't cover all cases | -| **Formal proof checking** | **Perfect, complete, unforgeable** | **Mathematical truth** | - -When the SLM suggests `induction n` and Coq says "proof complete", that is an -absolute ground truth. When it suggests `ring` and Coq says "this tactic failed", -that is an absolute ground truth. There is no label noise. There is no reward -hacking. The prover is an incorruptible teacher. - -This is the cleanest reinforcement signal in all of machine learning. - ---- - -## What Exists Today - -### Close Predecessors - -**AlphaProof (DeepMind, 2024):** -- Reinforcement learning + formal verification (Lean 4) for competition mathematics -- Solved 4/6 IMO 2024 problems at silver medal level -- Uses a large model, not an SLM; not self-directed -- Proves the concept: prover-as-training-signal works at the frontier - -**HTPS — Hyper-Tree Proof Search (Meta, 2022):** -- Online learning during proof search — the model improves as it searches -- Each successful/failed proof branch updates the policy -- Closest to "learning from the prover in real-time" -- But not self-directed; fixed curriculum - -**ReProver / LeanDojo (2023):** -- Retrieval-augmented theorem proving in Lean -- Trains on Mathlib proofs, retrieves relevant premises -- Shows that small specialised models can outperform large general ones on proofs - -**Draft, Sketch, Prove (2023):** -- LLM drafts informal proof → translator converts to formal → verifier checks -- Failed proofs are discarded, not learned from -- Missing the heutagogic loop - -**LEGO-Prover (2024):** -- LLM grows a verified lemma library over time -- Each proved lemma becomes available for future proofs -- Closest to "developing understanding over time" -- But the model weights don't update; only the lemma library grows - -### Neural-Symbolic Integration - -**DeepProbLog (KU Leuven, 2018-present):** -- Integrates neural networks with ProbLog (probabilistic logic programming) -- Neural predicates: neural network outputs become logic atoms -- Training: backpropagates through the logic program into the neural network -- **Key capability:** The logic constrains what the neural network can learn -- Directly relevant: could provide the "tethered" logical layer - -**NeurASP (2020):** -- Answer Set Programming + neural networks -- Logic rules constrain neural network training -- Can learn from logical inconsistencies (not just proof success/failure) - -**Logic Tensor Networks (LTN, 2022):** -- First-order logic with real-valued semantics -- Logical axioms become differentiable loss functions -- "Satisfying the axioms" = training the neural network - -**Scallop (2023):** -- Differentiable Datalog — backpropagates through logical reasoning -- Provenance tracking enables gradient computation through logical inference -- Could provide the "how did this proof step contribute?" signal - -### What Does NOT Exist (The Gap) - -No system currently combines all of these: - -1. ✅ Prover as training signal (AlphaProof, HTPS) -2. ✅ Small model that continues training (LoRA fine-tuning is routine) -3. ✅ Neural-symbolic integration (DeepProbLog, NeurASP, LTN) -4. ❌ **Self-directed curriculum** (the SLM chooses what to learn next) -5. ❌ **Two-layer tethered architecture** (stable reasoning + plastic adaptation) -6. ❌ **Overnight autonomous training** against a prover -7. ❌ **Domain-specific specialisation** that accumulates across sessions - -The user's proposal fills this gap. It is novel but entirely feasible given -existing components. - ---- - -## Architecture: Two-Layer Tethered SLM - -### The Problem with Vanilla Fine-Tuning - -If you fine-tune an SLM on proof data naively, you get catastrophic forgetting — it -learns new tactics but forgets how to parse goals. If you freeze it entirely, it -can't learn at all. The user's intuition about a "two-layer system where part is -tethered" maps precisely to a known solution. - -### Complementary Learning Systems (CLS) Architecture - -Inspired by how the human brain learns: the hippocampus learns quickly (one-shot, -today's proofs) while the neocortex consolidates slowly (overnight, generalised -patterns). This maps to: - -``` -┌─────────────────────────────────────────────────────────┐ -│ SLM Architecture │ -│ │ -│ ┌───────────────────────────────────────────────────┐ │ -│ │ Layer 1: TETHERED BASE (frozen weights) │ │ -│ │ │ │ -│ │ • Pre-trained language understanding │ │ -│ │ • Syntax parsing for Coq/Lean/SMT-LIB/etc. │ │ -│ │ • Basic logical reasoning patterns │ │ -│ │ • Natural language comprehension │ │ -│ │ │ │ -│ │ This layer NEVER changes. It provides stable │ │ -│ │ foundations that domain learning builds upon. │ │ -│ │ │ │ -│ │ Implementation: frozen base model weights │ │ -│ └───────────────────────────┬───────────────────────┘ │ -│ │ │ -│ ┌───────────────────────────▼───────────────────────┐ │ -│ │ Layer 2: PLASTIC ADAPTER (trainable LoRA) │ │ -│ │ │ │ -│ │ • Domain-specific tactic preferences │ │ -│ │ • Proof pattern recognition for THIS domain │ │ -│ │ • Learned heuristics from past proof attempts │ │ -│ │ • User-specific style adaptation │ │ -│ │ │ │ -│ │ This layer updates continuously from proof │ │ -│ │ feedback. Multiple adapters can coexist for │ │ -│ │ different domains (one for algebra, one for │ │ -│ │ protocol verification, one for type theory). │ │ -│ │ │ │ -│ │ Implementation: LoRA adapters (rank 8-16) │ │ -│ │ Storage: ~10-50 MB per domain adapter │ │ -│ └──────────────────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────┘ -``` - -**Why LoRA is the right mechanism:** -- Adapter weights are small (10-50 MB vs. gigabytes for full model) -- Multiple adapters can be swapped in/out for different domains -- Training is fast (minutes, not hours) -- The base model is never modified — stability is guaranteed -- Well-understood, battle-tested technique - -### The Heutagogic Loop - -Heutagogy = self-determined learning. The SLM doesn't just learn from proofs it's -asked to do — it decides what to learn next, based on where it's weakest. - -``` -┌──────────────────────────────────────────────────────────────┐ -│ Heutagogic Training Loop │ -│ │ -│ 1. SLM examines its own performance history │ -│ "I failed 7/10 induction proofs on lists but │ -│ succeeded 9/10 on natural numbers" │ -│ │ -│ 2. SLM selects training curriculum │ -│ "I should practice list induction tonight" │ -│ → Generates or selects proof goals from a library │ -│ │ -│ 3. SLM attempts proofs against ECHIDNA │ -│ → Tries tactics on the selected goals │ -│ → ECHIDNA returns success/failure for each step │ -│ │ -│ 4. SLM trains on results │ -│ → Successful proof traces become positive examples │ -│ → Failed attempts with prover diagnostics become │ -│ negative examples with correction signal │ -│ │ -│ 5. SLM evaluates improvement │ -│ → Re-attempts previously failed proofs │ -│ → If improved, moves to next weakness │ -│ → If stuck, escalates difficulty or tries new approach │ -│ │ -│ 6. Loop continues until budget exhausted (time/compute) │ -│ or target proficiency reached │ -│ │ -└──────────────────────────────────────────────────────────────┘ -``` - -**The curriculum is self-directed because:** -- The SLM tracks its own success/failure rates per tactic, per domain, per goal type -- It prioritises areas where it's weakest (exploration) or where small gains would - unlock the most downstream proofs (exploitation) -- It can generate its own training goals by mutating existing theorems (e.g., "if I - proved n + 0 = n, can I prove n * 1 = n?") -- It can request harder variants of goals it's already mastered - -### Overnight Training Protocol - -``` -┌──────────────────────────────────────────────────────────────┐ -│ OVERNIGHT TRAINING SCHEDULE (example) │ -│ │ -│ 22:00 SLM reviews today's proof sessions │ -│ → Identifies 12 failed tactic applications │ -│ → Clusters failures by type (3 induction, 4 rewrite, │ -│ 2 automation, 3 unfolding) │ -│ │ -│ 22:15 SLM generates training curriculum │ -│ → Selects 50 list induction goals from Mathlib │ -│ → Selects 40 rewriting exercises │ -│ → Generates 20 novel goals by mutation │ -│ │ -│ 22:30 Training loop begins │ -│ - SLM attempts goals → ECHIDNA validates │ -│ 05:30 → LoRA adapter weights updated after each batch │ -│ → ~110 goals attempted, ~70 eventually proved │ -│ → Progress logged to training journal │ -│ │ -│ 05:30 Evaluation checkpoint │ -│ → Re-attempt today's 12 failures │ -│ → 8/12 now succeed (67% recovery rate) │ -│ → Adapter saved as domain-v{N+1} │ -│ │ -│ 06:00 Training report ready for user │ -│ "Overnight: +15% on list induction, │ -│ +8% on rewriting, 2 goals still stuck │ -│ (suggest manual inspection)" │ -└──────────────────────────────────────────────────────────────┘ -``` - -**Resource budget:** An SLM (1-3B params) with LoRA training on a modern GPU uses -~4-8 GB VRAM and can process ~100 proof attempts per hour. Overnight (8 hours) = -~800 proof attempts, which is substantial curriculum coverage. - -**Without GPU:** CPU-only LoRA training is slower (~10-20 attempts/hour) but still -useful for focused domain training. A Threadripper or M-series Mac can handle this -comfortably overnight. - ---- - -## DeepProbLog Integration - -DeepProbLog provides something the pure LoRA approach doesn't: **logical constraints -on what the SLM can learn.** - -### How DeepProbLog Fits - -``` -┌──────────────────────────────────────────────────────────┐ -│ │ -│ ┌────────────┐ │ -│ │ SLM │──── tactic prediction ────┐ │ -│ │ (neural) │ │ │ -│ └────────────┘ ▼ │ -│ ▲ ┌─────────────────┐ │ -│ │ │ DeepProbLog │ │ -│ │ │ Logic Program │ │ -│ gradient │ │ │ -│ from logic │ • Type rules │ │ -│ │ │ • Tactic pre/ │ │ -│ │ │ postconditions│ │ -│ │ │ • Domain axioms │ │ -│ │ └────────┬────────┘ │ -│ │ │ │ -│ └───────────────────────────────────┘ │ -│ │ -│ Logic program constrains SLM training: │ -│ "If goal is ∀-quantified, intro is always valid" │ -│ "If goal is an equation, rewrite is relevant" │ -│ "induction requires a recursive type" │ -│ │ -└──────────────────────────────────────────────────────────┘ -``` - -**What DeepProbLog adds:** - -1. **Logical pre/postconditions as training constraints:** Instead of just "this - tactic succeeded/failed", DeepProbLog encodes WHY a tactic is applicable. The - gradient flows through the logical rules into the SLM, teaching it not just what - works but the structure of why. - -2. **Probabilistic reasoning about tactic choice:** DeepProbLog naturally handles - uncertainty. "induction is 80% likely to be the right tactic here" is a - probabilistic logic statement, not just a neural confidence score. - -3. **Compositional learning:** Logical rules compose. If the SLM learns that - "intro works on ∀-goals" and "induction works on nat-typed variables", it can - compose these to predict "intro then induction" on "∀ n : nat, ..." without - having seen that specific combination. - -4. **Explainability:** The logical program provides a human-readable explanation of - why the SLM made a prediction. "I chose induction because: (a) the goal contains - a recursive type (nat), (b) the goal is universally quantified, (c) my - experience with similar goals shows 87% success rate." - -### ProbLog Rules (Example) - -```prolog -% Neural predicate: SLM predicts tactic relevance -nn(tactic_net, [GoalType, GoalShape, Context], Tactic) :: tactic_relevant(Goal, Tactic). - -% Logical constraints (these constrain what the SLM can learn) -valid_tactic(Goal, intro) :- - goal_has_forall(Goal). - -valid_tactic(Goal, induction(Var)) :- - goal_has_forall(Goal), - variable_has_recursive_type(Var). - -valid_tactic(Goal, rewrite(Lemma)) :- - goal_is_equation(Goal), - lemma_matches_lhs(Lemma, Goal). - -% Combined: SLM prediction + logical validity -suggested_tactic(Goal, Tactic) :- - tactic_relevant(Goal, Tactic), - valid_tactic(Goal, Tactic). - -% Training signal: prover confirms or denies -proof_step_correct(Goal, Tactic) :- - suggested_tactic(Goal, Tactic), - echidna_validates(Goal, Tactic). -``` - -The key: `tactic_relevant` is a neural predicate (the SLM's output), but -`valid_tactic` is a logical constraint. DeepProbLog trains the SLM to satisfy -BOTH — it must predict tactics that are both neurally relevant AND logically valid. -This prevents the SLM from learning spurious correlations. - ---- - -## Risks and Mitigations - -| Risk | Severity | Mitigation | -|------|----------|------------| -| SLM overfits to training domain | Medium | Multiple LoRA adapters per domain; regularly evaluate on out-of-domain goals | -| Catastrophic forgetting in adapter | Low | LoRA rank is small; forgetting is bounded. Periodic adapter checkpoints allow rollback | -| Overnight training runs up compute costs | Low | SLM is small (1-3B); LoRA training is efficient; runs on local hardware | -| SLM learns wrong generalisations from limited proofs | Medium | DeepProbLog's logical constraints prevent logically invalid generalisations | -| Training loop diverges (gets worse, not better) | Medium | Evaluation checkpoints every N goals; auto-stop if accuracy drops below baseline | -| User trusts SLM too much after overnight improvement | Medium | Trust display always shows ECHIDNA's verification, not SLM's confidence; SLM is advisor, not oracle | -| Security: SLM training data leakage | Low | Training is local, no data leaves the machine; adapters can be encrypted at rest | - -### The Fundamental Safety Property - -**The prover is always the final authority.** No matter how much the SLM learns, its -output is always validated against ECHIDNA before being presented to the user as -correct. The SLM can become arbitrarily good at suggesting tactics, but it can never -claim a proof is valid — only the prover can do that. - -This is structurally different from LLM code generation, where the model's output is -executed directly. Here, the model's output is checked against mathematical truth -before execution. The worst case of a badly-trained SLM is bad suggestions, not -incorrect proofs. - ---- - -## Beyond Proofs: Reasoning Transfer - -The most speculative but most exciting possibility: **an SLM trained on formal proofs -might reason better about everything.** - -Formal proofs teach: -- **Logical structure:** Premises → conclusions, case analysis, contradiction -- **Precision:** Every step must be justified; no hand-waving -- **Abstraction:** Recognising when two problems have the same structure -- **Strategy:** When to try induction vs. case split vs. automation - -These are not proof-specific skills. They are general reasoning skills. An SLM that -has internalised "when I see a recursive structure, consider induction" from thousands -of proof attempts may apply that pattern to non-proof reasoning: "this data structure -is recursive, so the algorithm should be recursive too." - -This is speculative but testable. A concrete experiment: train an SLM on 10,000 Coq -proofs overnight, then evaluate it on non-proof reasoning benchmarks (ARC, GSM8K, -LogiQA). If scores improve, the proof training is teaching general reasoning. If -scores don't change, the learning is domain-specific (still valuable, just narrower). - ---- - -## Comparison to Existing Approaches - -| System | Learns from proofs? | Self-directed? | Two-layer? | Overnight? | Neural-symbolic? | -|--------|:-------------------:|:--------------:|:----------:|:----------:|:----------------:| -| AlphaProof | Yes | No (fixed curriculum) | No | No (massive cluster) | No | -| HTPS | Yes (online) | No | No | No | No | -| ReProver | Yes (offline) | No | No | No | No | -| LEGO-Prover | Yes (library only) | Partially | No | No | No | -| DeepProbLog | Not proofs specifically | No | Partially | No | Yes | -| **PanLL SLM** | **Yes** | **Yes (heutagogy)** | **Yes (LoRA)** | **Yes** | **Yes (DeepProbLog)** | - -Each component exists in isolation and is well-established. PanLL's contribution is -not invention but integration — pulling these into a single coherent workspace so -the user doesn't need 30 windows open. The combination is uncommon, but every -individual piece is proven technology. The value is the unified experience, not any -single component. - ---- - -## Implementation Phases - -### Phase A: Proof Replay Training (batch, no heutagogy) -- [ ] Collect proof traces from ECHIDNA sessions (successful and failed) -- [ ] Format as SLM training data (goal, context, tactic, outcome) -- [ ] LoRA fine-tune on collected traces -- [ ] Evaluate: does the adapter improve tactic suggestion accuracy? - -### Phase B: Online Learning (real-time, no self-direction) -- [ ] After each ECHIDNA validation, update adapter weights -- [ ] Implement replay buffer to prevent catastrophic forgetting -- [ ] Checkpoint adapter after each session - -### Phase C: Self-Directed Curriculum (heutagogy) -- [ ] SLM tracks success/failure rates per tactic + domain -- [ ] Curriculum selector: choose goals that target weakest areas -- [ ] Goal mutation: generate new goals from proved theorems -- [ ] Overnight training scheduler with evaluation checkpoints - -### Phase D: DeepProbLog Integration -- [ ] Define logical tactic preconditions in ProbLog -- [ ] Wire SLM as neural predicate in DeepProbLog -- [ ] Train through combined neural-symbolic pipeline -- [ ] Evaluate: does logical constraint improve learning efficiency? - -### Phase E: Multi-Domain Adapters -- [ ] Separate LoRA adapters per domain (algebra, lists, protocols, types) -- [ ] Adapter registry with metadata (domain, training history, accuracy) -- [ ] Auto-select adapter based on current proof context -- [ ] Cross-domain transfer experiments - ---- - -## Open Questions - -1. **Which SLM base model?** Candidates: Phi-3-mini (3.8B), Gemma-2-2B, Qwen2.5-1.5B, - CodeGemma-2B. Need: good code understanding, small enough for local LoRA training, - permissive license. - -2. **How much proof data is needed for meaningful adapter improvement?** Hypothesis: - 50-100 successful proofs per domain gives measurable improvement. Testable. - -3. **Should the SLM train on the full proof trace or just tactic-outcome pairs?** - Full traces give richer signal but are more expensive to process. - -4. **Can the heutagogic curriculum be itself learned?** Meta-learning: train a small - policy network that decides what the SLM should study next, based on improvement - rates across domains. - -5. **What is the right LoRA rank for proof domain adaptation?** Too low (2-4) may - underfit; too high (32-64) may overfit. Likely sweet spot: 8-16. - -6. **How does this interact with PanLL's trust display?** The trust level should - distinguish "SLM suggested this" (advisory) from "ECHIDNA verified this" (ground - truth). The SLM's confidence and the prover's verdict are independent signals. - -7. **Is DeepProbLog the right neural-symbolic framework?** Alternatives: NeurASP - (answer set programming), Scallop (differentiable Datalog), LTN (logic tensor - networks). DeepProbLog has the best probabilistic semantics but Scallop may be - faster for large-scale training. - ---- - -## References - -### Theorem Proving with ML -- Lample et al. (2022). "HyperTree Proof Search for Neural Theorem Proving." NeurIPS. -- Yang et al. (2023). "LeanDojo: Theorem Proving with Retrieval-Augmented Language Models." -- Jiang et al. (2023). "Draft, Sketch, and Prove: Guiding Formal Theorem Provers with Informal Proofs." -- Wang et al. (2024). "LEGO-Prover: Neural Theorem Proving with Growing Libraries." -- AlphaProof team (2024). "AI achieves silver-medal standard solving International Mathematical Olympiad problems." - -### Neural-Symbolic Learning -- Manhaeve et al. (2018). "DeepProbLog: Neural Probabilistic Logic Programming." NeurIPS. -- Yang et al. (2020). "NeurASP: Embracing Neural Networks into Answer Set Programming." -- Li et al. (2023). "Scallop: A Language for Neurosymbolic Programming." PLDI. -- Badreddine et al. (2022). "Logic Tensor Networks." Artificial Intelligence. - -### Continual Learning -- Hu et al. (2022). "LoRA: Low-Rank Adaptation of Large Language Models." ICLR. -- Kumaran et al. (2016). "What Learning Systems do Intelligent Agents Need? Complementary Learning Systems Theory Updated." Trends in Cognitive Sciences. - -### Self-Directed Learning -- Hase & Kenyon (2000). "From Andragogy to Heutagogy." UltiBASE. -- Schmidhuber (1991). "Curious Model-Building Control Systems." IJCNN. - -### Companion Design Documents -- `DESIGN-2026-02-28-echidna-proof-ux.md` — Proof UX and SLM advisory role -- `DESIGN-2026-02-28-discipline-layouts.md` — Domain-specific layouts -- `DESIGN-2026-02-28-collaboration.md` — Collaborative proof sessions diff --git a/docs/design/DESIGN-2026-02-28-strategic-assessment.adoc b/docs/design/DESIGN-2026-02-28-strategic-assessment.adoc new file mode 100644 index 00000000..7d25196e --- /dev/null +++ b/docs/design/DESIGN-2026-02-28-strategic-assessment.adoc @@ -0,0 +1,590 @@ +== DESIGN: PanLL Strategic Assessment — Dogfooding, Ordering, Competitors, and Hard Problems + +*Date:* 2026-02-28 *Repo:* panll *Author:* Jonathan D.A. Jewell +*Status:* Honest assessment (not aspirational — what actually is) + +=== Design Questions (from session dialogue) + +____ +"`Can you tell me from this integration point what you can see of the +dogfooded designs — how they are working, how they are failing, how they +can be bettered or if we need to rethink them?`" +____ + +____ +"`Can you give me oversight of the BIG plan and ordering as you see +it?`" +____ + +____ +"`What is the most readily comparable technology out there?`" +____ + +____ +"`What have you made to put back into the other repos with all of +this?`" +____ + +____ +"`What is there that you have looked at and thought damn, this is a HUGE +leap from what is out there — I just have no idea how it can be +achieved?`" +____ + +''''' + +=== A. Dogfooding Assessment — What’s Working, What’s Failing + +==== What’s Working Well + +*1. The Elm Architecture (Tea) in ReScript is rock-solid.* Model → +Update → View with immutable state updates. Every message is typed. +Every state transition is explicit. You can read Model.res and +understand the entire app state. This is the right architecture for a +tool this complex. + +*2. The type system documents the design.* 373 lines of types in +Model.res that read like a specification. `+echidnaTrustLevel+`, +`+axiomDangerLevel+`, `+portfolioConfidence+` — these aren’t just types, +they’re design decisions encoded in the compiler. A new contributor +reads Model.res and understands the domain. + +*3. ECHIDNA integration types match the API exactly.* The parsers handle +both success and failure paths. The mock server was trivial to write +because the types told me exactly what JSON shapes were needed. This is +what type-driven design gets you: the mock basically wrote itself from +the type defs. + +*4. Test coverage is genuine.* 121 Deno + 19 Rust tests. Not inflated — +they test real behaviour (tactic parsing, session lifecycle, trust level +mapping, axiom danger classification). When I changed the init data, +exactly the right tests broke. + +*5. Tauri separation of concerns.* Rust handles system operations (file +I/O, process spawning, HTTP requests). ReScript handles UI state. They +communicate through typed commands. Neither side does the other’s job. + +==== What’s Failing or Weak + +*1. ARIA gap — the most serious current problem.* The Tea_Vdom library +has 10 ARIA functions. The components barely use them. The README claims +"`ARIA accessibility across all components`" — this is false. The gap +between documentation claims and reality is a credibility risk. + +*2. Model.res is monolithic.* 557 lines in one file. The ECHIDNA types +alone (lines 263-373) could be their own module. The VeriSimDB types +could be their own module. Right now, every change to any type requires +reading through the entire file. Not a problem today, but will become +one as discipline layouts add more state. + +*3. UI state mixed into domain state.* `+menuExpanded+`, `+proofInput+`, +`+tacticInput+`, `+securityMenuExpanded+`, `+securityDialogOpen+` — +these are view/interaction state, not domain state. They’re mixed into +the same types as `+trustLevel+`, `+axiomReport+`, `+proofObligations+`. +This means: - Saving/loading state includes ephemeral UI state - The +model is larger than it needs to be - Testing domain logic requires +constructing UI state + +*4. Persistence should use VeriSimDB, not raw localStorage.* +localStorage saves the full model as JSON with no schema versioning. +When Model.res types change, old saved state breaks silently. But +VeriSimDB — which PanLL already integrates — is literally a versioned, +temporal, multi-modal database. PanLL should eat its own dog food: use +VeriSimDB for state persistence (versioned entities, temporal queries, +drift detection on its own state, proof provenance). localStorage +becomes an offline fallback cache, not the source of truth. + +*5. Unbounded growth.* `+paneN.tokens+` grows with every token added. +`+eventChain+` grows with every import. No pruning, no windowing, no +archival. Eventually this hits localStorage limits (typically 5-10 MB) +or causes UI jank from rendering thousands of tokens. + +*6. Error cascading.* A parse failure in ECHIDNA response handling +doesn’t have an error boundary. If `+parseEchidnaSession+` receives +malformed JSON, it returns defaults — but the defaults may be +semantically wrong (empty session ID). There should be explicit error +states, not silent defaults. + +==== What Should Be Rethought + +*1. The three-pane model is too rigid for discipline layouts.* Currently +Pane-L, Pane-N, Pane-W are hardcoded with fixed content types. The +discipline layouts design asks these panes to hold completely different +content depending on the layout (Pane-L is "`Proof Pipeline`" in Logic +mode but "`Schema Editor`" in Database mode). This needs either: - +Generic pane containers that host pluggable content components, or - A +pane registry where discipline layouts declare what component fills each +slot + +*2. The monologue is a string; it should be structured.* +`+paneN.monologue: string+` is a flat text field. For collaboration, +i18n, and screen readers, it should be a structured log with entries +that have timestamps, severity, and translatable message keys. + +*3. VeriSimDB and ECHIDNA follow the same pattern but aren’t +abstracted.* Both have: `+connected+`, `+endpoint+`, health check, list +items, CRUD operations, loading states, error states, menu expansion. A +shared `+backendService+` type would reduce duplication and make adding +new backends (QuandleDB, LithoGlyph) trivial. + +''''' + +=== B. The Big Plan and Ordering + +==== Ordering Principles + +[arabic] +. *Fix what’s broken before building what’s new* (accessibility before +features) +. *Infrastructure before features* (i18n framework before translations) +. *Each phase delivers usable value* (no phase is pure plumbing) +. *Dependencies flow forward* (later phases build on earlier ones) + +==== Phase Map + +.... +Phase 0: Foundation (THIS SESSION — DONE) +├── ✅ Mock ECHIDNA server on port 9000 +├── ✅ Demo neural tokens in Pane-N +├── ✅ All tests passing (19 Rust, 121 Deno, ReScript clean) +└── ✅ 5 design documents written + +Phase 1: Accessibility + Honesty Pass (NEXT — P0) +├── Close ARIA gap in all components +├── Add prefers-reduced-motion, prefers-contrast CSS +├── Keyboard navigation audit + fixes +├── Fix README claims to match reality +├── Add axe-core to CI +└── Deliverable: WCAG 2.3 A conformance (genuine) + +Phase 2: Model Refactoring (needed before features) +├── Split Model.res into domain modules +├── Separate UI state from domain state +├── Add schema versioning to persistence +├── Add token/event pruning with configurable limits +├── Abstract shared backend service pattern +└── Deliverable: Clean architecture for feature work + +Phase 3: Core Interoperability (P1) +├── Fuzzy search (pure ReScript, ~30 lines) +├── Pandoc export (AST JSON → multiple formats) +├── Zotero local API integration +├── Trustfile creation (from rsr-template-repo example) +└── Deliverable: Export proofs to papers, cite references + +Phase 4: Visual Proof Builder (P1) +├── Pipeline canvas component +├── Block palette with keyboard navigation +├── Proof state → pipeline graph conversion +├── Gap detection (constraint propagation) +├── How/why query hover popups +└── Deliverable: Blockly-style proof interaction + +Phase 5: Switchable Syntax + Linter (P1) +├── Syntax mode selector (Coq/Lean/SMT-LIB/Agda/Universal) +├── Per-prover syntax highlighting +├── Error → suggested correction engine +├── PanLL-Universal notation specification +└── Deliverable: Multi-prover text editing with corrections + +Phase 6: Discipline Layouts (P2) +├── Layout preset system (data model + switching) +├── 4 built-in presets (Logic, Database, Language, Protocol) +├── Custom layout save/load +├── Pane content registry (pluggable content per slot) +└── Deliverable: Adobe Connect-style viewshift + +Phase 7: Internationalisation (P2) +├── polyglot-i18n + LOL setup + en locale +├── Extract all hardcoded strings +├── RTL layout support (CSS logical properties) +├── Math notation screen reader localisation +└── Deliverable: Framework ready for translation contributions + +Phase 8: Collaboration (P2) +├── Elixir/Phoenix collaboration server +├── Shared proof state via Phoenix Channels +├── Contextual chat (on goals, entities, states) +├── WebRTC voice (ambient, Opus codec) +└── Deliverable: Real-time collaborative proof sessions + +Phase 9: SLM Integration (P3) +├── Local SLM hosting (Tauri sidecar or WASM) +├── NL → tactic translation +├── Proof state → plain English explainer +├── Guardrails (SLM output always validated by ECHIDNA) +└── Deliverable: Natural language proof interaction + +Phase 10: SLM Heutagogy (P3) +├── Proof trace collection and training data formatting +├── LoRA adapter training loop +├── Self-directed curriculum (weakness detection) +├── Overnight training scheduler +├── DeepProbLog integration (logical training constraints) +└── Deliverable: SLM that improves from proof experience + +Phase 11: OCR + Advanced Input (P3) +├── Tesseract for prose OCR +├── Nougat for mathematical OCR +├── Image/PDF drag-drop import +├── Handwritten math → proof goal conversion +└── Deliverable: Import proofs from papers and whiteboards + +Phase 12: Logical Notation Page (P3) +├── Symbol palettes (propositional → modal → temporal) +├── Multi-logic rendering +├── Notation ↔ prover translation layer +├── Ontology browser integration +└── Deliverable: The hard bridge (see section E) +.... + +==== Critical Path + +.... +Phase 1 (accessibility) ──▶ Phase 2 (refactor) ──▶ Phase 4 (visual builder) + ──▶ Phase 5 (syntax linter) + ──▶ Phase 6 (layouts) +Phase 3 (interop) can run in parallel with Phase 2 +Phase 7 (i18n) depends on Phase 2 (string extraction needs clean modules) +Phase 8 (collaboration) depends on Phase 6 (shared layout state) +Phase 9-10 (SLM) depend on Phase 4+5 (need the interaction patterns first) +Phase 12 (notation) depends on Phase 5 (builds on the syntax switching) +.... + +''''' + +=== C. Most Comparable Technology + +==== Direct Competitors (none are close) + +[width="100%",cols="24%,38%,38%",options="header",] +|=== +|Tool |What it does |What PanLL adds +|*Why3* |Multi-prover dispatch |Visual pipeline, collaboration, +accessibility, database integration + +|*Rodin (Event-B)* |Formal methods workbench |Modern UI, multi-prover, +neural component, not Eclipse-based + +|*Isabelle/jEdit* |ITP with IDE |Multi-prover, visual builder, +discipline layouts, collaboration + +|*Lean 4 + VS Code* |Modern ITP in editor |Multi-prover dispatch, +database, protocol, visual pipeline + +|*CoqIDE / VSCoq* |Coq-specific IDE |Multi-prover, visual builder, +everything else + +|*Wolfram* |Computation + notation |Formal _verification_ (not +computation), open-source, multi-prover + +|*Jupyter* |Computational notebooks |Proof-focused, pane model, formal +verification, typed state +|=== + +*Why3 is the closest ancestor* for the proof dispatch part. It +dispatches goals to multiple solvers (Z3, CVC5, Alt-Ergo, Coq, +Isabelle). But Why3 is: - Text-only (no visual pipeline) - Single-user +(no collaboration) - No database/protocol integration - No accessibility +focus - No neural/SLM component - Expert-only (no progressive +sophistication) + +*Wolfram is the closest _experience_ ancestor* — unified notation, mixed +computation and visualization, notebook-style interaction. But Wolfram: +- Does computation, not formal verification ("`simplify`" is not +"`prove`") - Proprietary and expensive - No multi-prover dispatch - No +collaboration - No accessibility standards - Sidesteps the hard problem +entirely by not doing proofs + +*The honest summary:* Nothing out there combines multi-prover dispatch + +visual proof pipeline + database integration + protocol verification + +discipline layouts + collaboration + accessibility + i18n + SLM. Each +piece exists individually. PanLL is an integration play, not an +invention play. + +''''' + +=== D. Feedback to Other Repos + +==== Concrete Insights That Feed Back + +*1. ReScript Evangeliser ← Progressive sophistication model* The 4-level +model (Visual → Syntax → Logic → REPL) directly maps to the +Evangeliser’s view layers (RAW → FOLDED → GLYPHED → WYSIWYG). The +switchable linter infrastructure could be a shared ReScript library used +by both. The confidence-scored suggestions and celebrate-don’t-shame +feedback patterns are identical. + +_Specific change:_ The Evangeliser’s WYSIWYG layer (Phase 4, not yet +implemented) should be designed as a Blockly-style visual editor, not a +rich text editor. This session’s proof pipeline design proves the +pattern works for code transformation. + +*2. ECHIDNA ← Mock server defines the API contract* The mock server +(`+scripts/mock-echidna.ts+`) is the clearest documentation of what +ECHIDNA’s API should return. The JSON shapes, field names, and response +semantics are all tested against PanLL’s actual parsers. This should be +extracted as an OpenAPI spec and committed to the ECHIDNA repo. + +*3. VeriSimDB ← Discipline layout reveals the query UX gap* The Database +Design layout shows that VeriSimDB’s query interface needs a visual +query builder (not just text VCL-DT input). The drift heatmap and +telemetry dashboard are genuinely useful UI patterns that should be +designed as standalone components reusable outside PanLL. + +*4. rsr-template-repo ← Trustfile needs WCAG section* The Trustfile +template should include an accessibility declaration section. Every RSR +repo that has a UI component should declare its WCAG conformance level. +This is a new template addition. + +*5. Proven repo ← Trust levels map to axiom audit* ECHIDNA’s +`+axiomDangerLevel+` (Safe → Noted → Warning → Reject) and +`+echidnaTrustLevel+` (1-5) are exactly the classification system needed +for the Proven repo audit. The 4,566 `+believe_me+` instances in Proven +would all be `+Reject+` level, giving a Trust Level of 1. This could be +automated: run ECHIDNA’s axiom scanner across Proven’s Idris2 code and +generate the trust report automatically. + +*6. Echidnabot ← Axiom danger levels should use ECHIDNA’s +classification* Echidnabot currently flags `+believe_me+`, `+Admitted+`, +`+sorry+` as CRITICAL. ECHIDNA’s 4-level classification +(Safe/Noted/Warning/Reject) is more nuanced. Echidnabot should adopt it, +making the bot’s output directly consumable by PanLL’s trust display. + +*7. IDApTIK Level Architect ← VeriSimDB persistence pattern* The level +data model uses VeriSimDB for persistence. The Database Design layout in +PanLL would let level designers browse, query, and verify level data +directly. The cross-domain proofs (InRegistry, GuardsInZones, etc.) +could be verified through ECHIDNA’s dispatch. + +*8. DeepProbLog / Neural-symbolic ← Idris2 ABI as training constraints* +The ABI/FFI standard (Idris2 for ABI definitions) could provide the +logical constraints for SLM training. Dependent types in Idris2 proving +interface correctness → these become the DeepProbLog rules that +constrain what the SLM can learn. Formal types as training guardrails. + +*9. Fuzzy search ← Publishable standalone module* The +Levenshtein/BK-tree fuzzy search is useful in: NQC web UI (keyword +search), ReScript Evangeliser (pattern matching), any tool with a +command palette. Should be a shared package in +`+developer-ecosystem/rescript-ecosystem/packages/+`. + +*10. Pandoc export ← Universal for all hyperpolymath docs* If PanLL gets +Pandoc AST JSON export, the same infrastructure can be used by any repo +that needs multi-format documentation. The custom Pandoc filters for +proof rendering could be shared. + +''''' + +=== E. The Hardest Leap — And What I Don’t Know How to Solve + +==== The User’s Instinct Is Correct + +____ +"`In my head the hardest thing looks like the bridge between the logical +notation mode and what fits around it in terms of the provers and +ontologies. I have not seen that done properly anywhere else — most +things being really very focused on either hard very concrete stuff or +abstract theoretical stuff.`" +____ + +This is exactly right, and it’s the fundamental unsolved problem in +formal methods tooling. + +==== The Problem, Precisely + +When someone writes `+∀ n : ℕ, n + 0 = n+` in PanLL-Universal notation, +they mean one thing. But the provers mean different things: + +[width="100%",cols="14%,57%,29%",options="header",] +|=== +|Prover |Syntax |Semantics +|Coq |`+forall n : nat, n + 0 = n+` |Dependent type (CIC) + +|Lean 4 |`+∀ n : Nat, n + 0 = n+` |Dependent type (CIC variant) + +|Isabelle |`+∀n::nat. n + 0 = n+` |Higher-order logic (HOL) + +|Z3 |`+(assert (forall ((n Int)) (= (+ n 0) n)))+` |First-order + +theories (SMT) + +|Agda |`+∀ n → n + 0 ≡ n+` |Dependent type (MLTT) +|=== + +These are NOT syntactic differences. They are *semantic* differences: + +* Coq’s `+forall+` is a Π-type in the Calculus of Inductive +Constructions +* Z3’s `+forall+` is first-order quantification over a decided theory +* Isabelle’s `+∀+` is higher-order logic quantification +* Agda’s `+∀+` is a dependent function type in Martin-Löf Type Theory + +The same symbol means different things. A proof that works in Coq +doesn’t automatically work in Lean (despite both being CIC-based) +because their standard libraries define `+nat+` and `+++` differently. A +proof in Isabelle uses completely different foundations. + +==== Why This Is Hard (Not Just Engineering) + +*The translation is not syntactic — it’s semantic.* You can write a +regex to convert `+forall+` to `+∀+`. You cannot write a regex to +convert CIC to HOL. These are different mathematical foundations with +different notions of: - What counts as a valid proof - What axioms are +available - How induction works - Whether classical or constructive +logic applies - How universe levels interact + +*Ontologies make it worse.* OWL/MOF/SKOS formalise domain knowledge ("`a +Vehicle is a subclass of PhysicalObject`") but don’t connect to provers. +You can express the ontology but you can’t prove properties about it +without manual translation into a prover’s language. And different +ontology languages have different expressiveness (OWL-DL is decidable, +OWL-Full is not). + +==== What Exists (Partial Solutions) + +[width="100%",cols="21%,42%,37%",options="header",] +|=== +|Tool/Framework |What it does |Why it’s not enough +|*Dedukti/Lambdapi* |Logical framework encoding multiple logics +|Expert-only, no UI, no ontologies + +|*MMT* |Universal framework for formal systems |Academic, not +user-facing + +|*TPTP* |Standard syntax for ATP |First-order only + +|*OpenTheory* |Proof sharing between HOL systems |HOL family only + +|*Logipedia* |Library of proofs across systems |Catalogue, not +interactive + +|*Hets* |Heterogeneous specification |Multi-logic but no visual UX + +|*DOL (Distributed Ontology Language)* |Links ontologies to logics +|Specification-stage, no tooling +|=== + +==== What Wolfram Actually Does (And Doesn’t) + +Wolfram has beautiful unified notation and handles everything from +arithmetic to differential equations to graph theory in one environment. +But it *does not do formal verification*. When Wolfram says +`+Simplify[x^2 - 1] = (x-1)(x+1)+`, that is a _computation_, not a +_proof_. The result might be wrong for edge cases (complex numbers, +special values) and Wolfram provides no certificate. + +Wolfram sidesteps the entire hard problem by operating in the "`concrete +computation`" world, not the "`formal proof`" world. PanLL can’t do that +— the whole point is verified proofs with trust levels. + +==== How PanLL Might Bridge the Gap + +*Layer 1: Semantic type classes* + +Instead of translating syntax, define semantic interfaces that provers +implement: + +.... +-- PanLL-Universal semantic interface +typeclass NaturalNumber T where + zero : T + succ : T → T + induction : (P : T → Prop) → P zero → (∀ n, P n → P (succ n)) → ∀ n, P n + +-- Coq implementation: nat with Peano axioms +-- Lean implementation: Nat with Mathlib +-- Isabelle implementation: nat with HOL-Library +-- Z3 implementation: Int with (>= 0) constraint (approximate) +.... + +The PanLL-Universal statement `+∀ n : Nat, n + 0 = n+` maps to the +`+NaturalNumber+` typeclass, and each prover backend provides its own +implementation. The translation is at the typeclass boundary, not the +syntax level. + +*Layer 2: The SLM as semantic translator* + +This is where the SLM earns its keep. Instead of rule-based translation +(which requires encoding every prover’s semantics manually), train the +SLM on parallel corpora: - Coq’s Mathlib proofs - Lean’s Mathlib proofs +(which share many theorems) - Isabelle’s AFP proofs + +The SLM learns the semantic mapping between systems. When a user writes +a goal in PanLL-Universal, the SLM translates to each target prover — +and crucially, the prover validates the translation. Bad translations +are caught by the type checker. + +This is where the heutagogic training loop becomes essential: the SLM +gets better at cross-system translation over time, learning from its own +failures. + +*Layer 3: Ontology grounding via Description Logic provers* + +For the ontology side, use Description Logic reasoners (HermiT, ELK, +Konclude) as a bridge: - User defines domain ontology in a visual editor +(part of the proof pipeline) - Ontology is checked by a DL reasoner for +consistency - Relevant ontological facts are extracted and encoded as +prover axioms - ECHIDNA dispatches the proof with these axioms available + +This doesn’t solve the full problem but it handles the common case: "`I +have a domain model, I want to prove properties about it.`" + +==== The Honest Assessment + +*I don’t know how to fully solve this.* The semantic gap between logics +is a research problem, not an engineering problem. Dedukti/Lambdapi +comes closest but it requires users to understand logical frameworks — +which defeats the progressive sophistication goal. + +The most promising path is the combination of: 1. Semantic typeclasses +(narrow the problem to common mathematical structures) 2. SLM +translation (handle the cases typeclasses don’t cover) 3. Prover +validation (catch translation errors) 4. Honest degradation (tell the +user when a goal can’t be faithfully translated to a particular prover, +rather than silently producing something wrong) + +This is Phase 12 for a reason. It’s the hardest, it depends on +everything else working, and it may require research breakthroughs — not +just engineering. + +''''' + +=== F. Summary + +[width="100%",cols="56%,44%",options="header",] +|=== +|Question |Answer +|What’s working? |Elm architecture, typed domain model, test coverage, +Tauri separation + +|What’s failing? |ARIA gap, monolithic model, mixed UI/domain state, no +schema versioning + +|What needs rethinking? |Rigid pane model, flat monologue, duplicated +backend patterns + +|Big plan ordering? |Accessibility → Refactor → Interop → Visual → +Syntax → Layouts → i18n → Collab → SLM → Notation + +|Closest competitor? |Why3 (dispatch) + Wolfram (experience) — but +nothing combines all pieces + +|Feedback to other repos? |10 concrete insights (Evangeliser, ECHIDNA +API, VeriSimDB UX, Trustfile, Proven audit, Echidnabot, IDApTIK, +DeepProbLog, fuzzy search, Pandoc) + +|Hardest unsolved problem? |Semantic translation between logics + +ontology grounding — the bridge between notation and provers +|=== + +''''' + +=== References + +* Why3: https://why3.lri.fr/ +* Dedukti: https://deducteam.github.io/ +* MMT: https://uniformal.github.io/ +* DOL: https://dol-omg.github.io/ +* Logipedia: https://logipedia.inria.fr/ +* Wolfram Language: https://www.wolfram.com/language/ +* Companion design documents in this directory diff --git a/docs/design/DESIGN-2026-02-28-strategic-assessment.md b/docs/design/DESIGN-2026-02-28-strategic-assessment.md deleted file mode 100644 index 17af5895..00000000 --- a/docs/design/DESIGN-2026-02-28-strategic-assessment.md +++ /dev/null @@ -1,518 +0,0 @@ -# DESIGN: PanLL Strategic Assessment — Dogfooding, Ordering, Competitors, and Hard Problems - -**Date:** 2026-02-28 -**Repo:** panll -**Author:** Jonathan D.A. Jewell -**Status:** Honest assessment (not aspirational — what actually is) - -## Design Questions (from session dialogue) - -> "Can you tell me from this integration point what you can see of the dogfooded -> designs — how they are working, how they are failing, how they can be bettered or -> if we need to rethink them?" - -> "Can you give me oversight of the BIG plan and ordering as you see it?" - -> "What is the most readily comparable technology out there?" - -> "What have you made to put back into the other repos with all of this?" - -> "What is there that you have looked at and thought damn, this is a HUGE leap from -> what is out there — I just have no idea how it can be achieved?" - ---- - -## A. Dogfooding Assessment — What's Working, What's Failing - -### What's Working Well - -**1. The Elm Architecture (Tea) in ReScript is rock-solid.** -Model → Update → View with immutable state updates. Every message is typed. Every -state transition is explicit. You can read Model.res and understand the entire app -state. This is the right architecture for a tool this complex. - -**2. The type system documents the design.** -373 lines of types in Model.res that read like a specification. `echidnaTrustLevel`, -`axiomDangerLevel`, `portfolioConfidence` — these aren't just types, they're design -decisions encoded in the compiler. A new contributor reads Model.res and understands -the domain. - -**3. ECHIDNA integration types match the API exactly.** -The parsers handle both success and failure paths. The mock server was trivial to -write because the types told me exactly what JSON shapes were needed. This is what -type-driven design gets you: the mock basically wrote itself from the type defs. - -**4. Test coverage is genuine.** -121 Deno + 19 Rust tests. Not inflated — they test real behaviour (tactic parsing, -session lifecycle, trust level mapping, axiom danger classification). When I changed -the init data, exactly the right tests broke. - -**5. Tauri separation of concerns.** -Rust handles system operations (file I/O, process spawning, HTTP requests). ReScript -handles UI state. They communicate through typed commands. Neither side does the -other's job. - -### What's Failing or Weak - -**1. ARIA gap — the most serious current problem.** -The Tea_Vdom library has 10 ARIA functions. The components barely use them. The -README claims "ARIA accessibility across all components" — this is false. The gap -between documentation claims and reality is a credibility risk. - -**2. Model.res is monolithic.** -557 lines in one file. The ECHIDNA types alone (lines 263-373) could be their own -module. The VeriSimDB types could be their own module. Right now, every change to -any type requires reading through the entire file. Not a problem today, but will -become one as discipline layouts add more state. - -**3. UI state mixed into domain state.** -`menuExpanded`, `proofInput`, `tacticInput`, `securityMenuExpanded`, -`securityDialogOpen` — these are view/interaction state, not domain state. They're -mixed into the same types as `trustLevel`, `axiomReport`, `proofObligations`. -This means: -- Saving/loading state includes ephemeral UI state -- The model is larger than it needs to be -- Testing domain logic requires constructing UI state - -**4. Persistence should use VeriSimDB, not raw localStorage.** -localStorage saves the full model as JSON with no schema versioning. When Model.res -types change, old saved state breaks silently. But VeriSimDB — which PanLL already -integrates — is literally a versioned, temporal, multi-modal database. PanLL should -eat its own dog food: use VeriSimDB for state persistence (versioned entities, -temporal queries, drift detection on its own state, proof provenance). localStorage -becomes an offline fallback cache, not the source of truth. - -**5. Unbounded growth.** -`paneN.tokens` grows with every token added. `eventChain` grows with every import. -No pruning, no windowing, no archival. Eventually this hits localStorage limits -(typically 5-10 MB) or causes UI jank from rendering thousands of tokens. - -**6. Error cascading.** -A parse failure in ECHIDNA response handling doesn't have an error boundary. If -`parseEchidnaSession` receives malformed JSON, it returns defaults — but the -defaults may be semantically wrong (empty session ID). There should be explicit -error states, not silent defaults. - -### What Should Be Rethought - -**1. The three-pane model is too rigid for discipline layouts.** -Currently Pane-L, Pane-N, Pane-W are hardcoded with fixed content types. The -discipline layouts design asks these panes to hold completely different content -depending on the layout (Pane-L is "Proof Pipeline" in Logic mode but "Schema -Editor" in Database mode). This needs either: -- Generic pane containers that host pluggable content components, or -- A pane registry where discipline layouts declare what component fills each slot - -**2. The monologue is a string; it should be structured.** -`paneN.monologue: string` is a flat text field. For collaboration, i18n, and -screen readers, it should be a structured log with entries that have timestamps, -severity, and translatable message keys. - -**3. VeriSimDB and ECHIDNA follow the same pattern but aren't abstracted.** -Both have: `connected`, `endpoint`, health check, list items, CRUD operations, -loading states, error states, menu expansion. A shared `backendService` type -would reduce duplication and make adding new backends (QuandleDB, LithoGlyph) -trivial. - ---- - -## B. The Big Plan and Ordering - -### Ordering Principles - -1. **Fix what's broken before building what's new** (accessibility before features) -2. **Infrastructure before features** (i18n framework before translations) -3. **Each phase delivers usable value** (no phase is pure plumbing) -4. **Dependencies flow forward** (later phases build on earlier ones) - -### Phase Map - -``` -Phase 0: Foundation (THIS SESSION — DONE) -├── ✅ Mock ECHIDNA server on port 9000 -├── ✅ Demo neural tokens in Pane-N -├── ✅ All tests passing (19 Rust, 121 Deno, ReScript clean) -└── ✅ 5 design documents written - -Phase 1: Accessibility + Honesty Pass (NEXT — P0) -├── Close ARIA gap in all components -├── Add prefers-reduced-motion, prefers-contrast CSS -├── Keyboard navigation audit + fixes -├── Fix README claims to match reality -├── Add axe-core to CI -└── Deliverable: WCAG 2.3 A conformance (genuine) - -Phase 2: Model Refactoring (needed before features) -├── Split Model.res into domain modules -├── Separate UI state from domain state -├── Add schema versioning to persistence -├── Add token/event pruning with configurable limits -├── Abstract shared backend service pattern -└── Deliverable: Clean architecture for feature work - -Phase 3: Core Interoperability (P1) -├── Fuzzy search (pure ReScript, ~30 lines) -├── Pandoc export (AST JSON → multiple formats) -├── Zotero local API integration -├── Trustfile creation (from rsr-template-repo example) -└── Deliverable: Export proofs to papers, cite references - -Phase 4: Visual Proof Builder (P1) -├── Pipeline canvas component -├── Block palette with keyboard navigation -├── Proof state → pipeline graph conversion -├── Gap detection (constraint propagation) -├── How/why query hover popups -└── Deliverable: Blockly-style proof interaction - -Phase 5: Switchable Syntax + Linter (P1) -├── Syntax mode selector (Coq/Lean/SMT-LIB/Agda/Universal) -├── Per-prover syntax highlighting -├── Error → suggested correction engine -├── PanLL-Universal notation specification -└── Deliverable: Multi-prover text editing with corrections - -Phase 6: Discipline Layouts (P2) -├── Layout preset system (data model + switching) -├── 4 built-in presets (Logic, Database, Language, Protocol) -├── Custom layout save/load -├── Pane content registry (pluggable content per slot) -└── Deliverable: Adobe Connect-style viewshift - -Phase 7: Internationalisation (P2) -├── polyglot-i18n + LOL setup + en locale -├── Extract all hardcoded strings -├── RTL layout support (CSS logical properties) -├── Math notation screen reader localisation -└── Deliverable: Framework ready for translation contributions - -Phase 8: Collaboration (P2) -├── Elixir/Phoenix collaboration server -├── Shared proof state via Phoenix Channels -├── Contextual chat (on goals, entities, states) -├── WebRTC voice (ambient, Opus codec) -└── Deliverable: Real-time collaborative proof sessions - -Phase 9: SLM Integration (P3) -├── Local SLM hosting (Tauri sidecar or WASM) -├── NL → tactic translation -├── Proof state → plain English explainer -├── Guardrails (SLM output always validated by ECHIDNA) -└── Deliverable: Natural language proof interaction - -Phase 10: SLM Heutagogy (P3) -├── Proof trace collection and training data formatting -├── LoRA adapter training loop -├── Self-directed curriculum (weakness detection) -├── Overnight training scheduler -├── DeepProbLog integration (logical training constraints) -└── Deliverable: SLM that improves from proof experience - -Phase 11: OCR + Advanced Input (P3) -├── Tesseract for prose OCR -├── Nougat for mathematical OCR -├── Image/PDF drag-drop import -├── Handwritten math → proof goal conversion -└── Deliverable: Import proofs from papers and whiteboards - -Phase 12: Logical Notation Page (P3) -├── Symbol palettes (propositional → modal → temporal) -├── Multi-logic rendering -├── Notation ↔ prover translation layer -├── Ontology browser integration -└── Deliverable: The hard bridge (see section E) -``` - -### Critical Path - -``` -Phase 1 (accessibility) ──▶ Phase 2 (refactor) ──▶ Phase 4 (visual builder) - ──▶ Phase 5 (syntax linter) - ──▶ Phase 6 (layouts) -Phase 3 (interop) can run in parallel with Phase 2 -Phase 7 (i18n) depends on Phase 2 (string extraction needs clean modules) -Phase 8 (collaboration) depends on Phase 6 (shared layout state) -Phase 9-10 (SLM) depend on Phase 4+5 (need the interaction patterns first) -Phase 12 (notation) depends on Phase 5 (builds on the syntax switching) -``` - ---- - -## C. Most Comparable Technology - -### Direct Competitors (none are close) - -| Tool | What it does | What PanLL adds | -|--------------------|----------------------------------|----------------------------------| -| **Why3** | Multi-prover dispatch | Visual pipeline, collaboration, accessibility, database integration | -| **Rodin (Event-B)**| Formal methods workbench | Modern UI, multi-prover, neural component, not Eclipse-based | -| **Isabelle/jEdit** | ITP with IDE | Multi-prover, visual builder, discipline layouts, collaboration | -| **Lean 4 + VS Code**| Modern ITP in editor | Multi-prover dispatch, database, protocol, visual pipeline | -| **CoqIDE / VSCoq** | Coq-specific IDE | Multi-prover, visual builder, everything else | -| **Wolfram** | Computation + notation | Formal *verification* (not computation), open-source, multi-prover | -| **Jupyter** | Computational notebooks | Proof-focused, pane model, formal verification, typed state | - -**Why3 is the closest ancestor** for the proof dispatch part. It dispatches goals -to multiple solvers (Z3, CVC5, Alt-Ergo, Coq, Isabelle). But Why3 is: -- Text-only (no visual pipeline) -- Single-user (no collaboration) -- No database/protocol integration -- No accessibility focus -- No neural/SLM component -- Expert-only (no progressive sophistication) - -**Wolfram is the closest *experience* ancestor** — unified notation, mixed -computation and visualization, notebook-style interaction. But Wolfram: -- Does computation, not formal verification ("simplify" is not "prove") -- Proprietary and expensive -- No multi-prover dispatch -- No collaboration -- No accessibility standards -- Sidesteps the hard problem entirely by not doing proofs - -**The honest summary:** Nothing out there combines multi-prover dispatch + visual -proof pipeline + database integration + protocol verification + discipline layouts -+ collaboration + accessibility + i18n + SLM. Each piece exists individually. PanLL -is an integration play, not an invention play. - ---- - -## D. Feedback to Other Repos - -### Concrete Insights That Feed Back - -**1. ReScript Evangeliser ← Progressive sophistication model** -The 4-level model (Visual → Syntax → Logic → REPL) directly maps to the -Evangeliser's view layers (RAW → FOLDED → GLYPHED → WYSIWYG). The switchable -linter infrastructure could be a shared ReScript library used by both. The -confidence-scored suggestions and celebrate-don't-shame feedback patterns are -identical. - -*Specific change:* The Evangeliser's WYSIWYG layer (Phase 4, not yet implemented) -should be designed as a Blockly-style visual editor, not a rich text editor. This -session's proof pipeline design proves the pattern works for code transformation. - -**2. ECHIDNA ← Mock server defines the API contract** -The mock server (`scripts/mock-echidna.ts`) is the clearest documentation of what -ECHIDNA's API should return. The JSON shapes, field names, and response semantics -are all tested against PanLL's actual parsers. This should be extracted as an -OpenAPI spec and committed to the ECHIDNA repo. - -**3. VeriSimDB ← Discipline layout reveals the query UX gap** -The Database Design layout shows that VeriSimDB's query interface needs a visual -query builder (not just text VCL-DT input). The drift heatmap and telemetry dashboard -are genuinely useful UI patterns that should be designed as standalone components -reusable outside PanLL. - -**4. rsr-template-repo ← Trustfile needs WCAG section** -The Trustfile template should include an accessibility declaration section. Every RSR -repo that has a UI component should declare its WCAG conformance level. This is a -new template addition. - -**5. Proven repo ← Trust levels map to axiom audit** -ECHIDNA's `axiomDangerLevel` (Safe → Noted → Warning → Reject) and `echidnaTrustLevel` -(1-5) are exactly the classification system needed for the Proven repo audit. The -4,566 `believe_me` instances in Proven would all be `Reject` level, giving a Trust -Level of 1. This could be automated: run ECHIDNA's axiom scanner across Proven's -Idris2 code and generate the trust report automatically. - -**6. Echidnabot ← Axiom danger levels should use ECHIDNA's classification** -Echidnabot currently flags `believe_me`, `Admitted`, `sorry` as CRITICAL. ECHIDNA's -4-level classification (Safe/Noted/Warning/Reject) is more nuanced. Echidnabot -should adopt it, making the bot's output directly consumable by PanLL's trust display. - -**7. IDApTIK Level Architect ← VeriSimDB persistence pattern** -The level data model uses VeriSimDB for persistence. The Database Design layout in -PanLL would let level designers browse, query, and verify level data directly. The -cross-domain proofs (InRegistry, GuardsInZones, etc.) could be verified through -ECHIDNA's dispatch. - -**8. DeepProbLog / Neural-symbolic ← Idris2 ABI as training constraints** -The ABI/FFI standard (Idris2 for ABI definitions) could provide the logical -constraints for SLM training. Dependent types in Idris2 proving interface -correctness → these become the DeepProbLog rules that constrain what the SLM -can learn. Formal types as training guardrails. - -**9. Fuzzy search ← Publishable standalone module** -The Levenshtein/BK-tree fuzzy search is useful in: NQC web UI (keyword search), -ReScript Evangeliser (pattern matching), any tool with a command palette. Should be -a shared package in `developer-ecosystem/rescript-ecosystem/packages/`. - -**10. Pandoc export ← Universal for all hyperpolymath docs** -If PanLL gets Pandoc AST JSON export, the same infrastructure can be used by any -repo that needs multi-format documentation. The custom Pandoc filters for proof -rendering could be shared. - ---- - -## E. The Hardest Leap — And What I Don't Know How to Solve - -### The User's Instinct Is Correct - -> "In my head the hardest thing looks like the bridge between the logical notation -> mode and what fits around it in terms of the provers and ontologies. I have not -> seen that done properly anywhere else — most things being really very focused on -> either hard very concrete stuff or abstract theoretical stuff." - -This is exactly right, and it's the fundamental unsolved problem in formal methods -tooling. - -### The Problem, Precisely - -When someone writes `∀ n : ℕ, n + 0 = n` in PanLL-Universal notation, they mean -one thing. But the provers mean different things: - -| Prover | Syntax | Semantics | -|-----------|-----------------------------------------------|------------------------| -| Coq | `forall n : nat, n + 0 = n` | Dependent type (CIC) | -| Lean 4 | `∀ n : Nat, n + 0 = n` | Dependent type (CIC variant) | -| Isabelle | `∀n::nat. n + 0 = n` | Higher-order logic (HOL) | -| Z3 | `(assert (forall ((n Int)) (= (+ n 0) n)))` | First-order + theories (SMT) | -| Agda | `∀ n → n + 0 ≡ n` | Dependent type (MLTT) | - -These are NOT syntactic differences. They are **semantic** differences: - -- Coq's `forall` is a Π-type in the Calculus of Inductive Constructions -- Z3's `forall` is first-order quantification over a decided theory -- Isabelle's `∀` is higher-order logic quantification -- Agda's `∀` is a dependent function type in Martin-Löf Type Theory - -The same symbol means different things. A proof that works in Coq doesn't -automatically work in Lean (despite both being CIC-based) because their standard -libraries define `nat` and `+` differently. A proof in Isabelle uses completely -different foundations. - -### Why This Is Hard (Not Just Engineering) - -**The translation is not syntactic — it's semantic.** You can write a regex to -convert `forall` to `∀`. You cannot write a regex to convert CIC to HOL. These -are different mathematical foundations with different notions of: -- What counts as a valid proof -- What axioms are available -- How induction works -- Whether classical or constructive logic applies -- How universe levels interact - -**Ontologies make it worse.** OWL/MOF/SKOS formalise domain knowledge ("a Vehicle -is a subclass of PhysicalObject") but don't connect to provers. You can express -the ontology but you can't prove properties about it without manual translation -into a prover's language. And different ontology languages have different -expressiveness (OWL-DL is decidable, OWL-Full is not). - -### What Exists (Partial Solutions) - -| Tool/Framework | What it does | Why it's not enough | -|----------------|----------------------------------|------------------------------| -| **Dedukti/Lambdapi** | Logical framework encoding multiple logics | Expert-only, no UI, no ontologies | -| **MMT** | Universal framework for formal systems | Academic, not user-facing | -| **TPTP** | Standard syntax for ATP | First-order only | -| **OpenTheory** | Proof sharing between HOL systems | HOL family only | -| **Logipedia** | Library of proofs across systems | Catalogue, not interactive | -| **Hets** | Heterogeneous specification | Multi-logic but no visual UX | -| **DOL (Distributed Ontology Language)** | Links ontologies to logics | Specification-stage, no tooling | - -### What Wolfram Actually Does (And Doesn't) - -Wolfram has beautiful unified notation and handles everything from arithmetic to -differential equations to graph theory in one environment. But it **does not do -formal verification**. When Wolfram says `Simplify[x^2 - 1] = (x-1)(x+1)`, that -is a *computation*, not a *proof*. The result might be wrong for edge cases -(complex numbers, special values) and Wolfram provides no certificate. - -Wolfram sidesteps the entire hard problem by operating in the "concrete computation" -world, not the "formal proof" world. PanLL can't do that — the whole point is -verified proofs with trust levels. - -### How PanLL Might Bridge the Gap - -**Layer 1: Semantic type classes** - -Instead of translating syntax, define semantic interfaces that provers implement: - -``` --- PanLL-Universal semantic interface -typeclass NaturalNumber T where - zero : T - succ : T → T - induction : (P : T → Prop) → P zero → (∀ n, P n → P (succ n)) → ∀ n, P n - --- Coq implementation: nat with Peano axioms --- Lean implementation: Nat with Mathlib --- Isabelle implementation: nat with HOL-Library --- Z3 implementation: Int with (>= 0) constraint (approximate) -``` - -The PanLL-Universal statement `∀ n : Nat, n + 0 = n` maps to the `NaturalNumber` -typeclass, and each prover backend provides its own implementation. The translation -is at the typeclass boundary, not the syntax level. - -**Layer 2: The SLM as semantic translator** - -This is where the SLM earns its keep. Instead of rule-based translation (which -requires encoding every prover's semantics manually), train the SLM on parallel -corpora: -- Coq's Mathlib proofs -- Lean's Mathlib proofs (which share many theorems) -- Isabelle's AFP proofs - -The SLM learns the semantic mapping between systems. When a user writes a goal in -PanLL-Universal, the SLM translates to each target prover — and crucially, the -prover validates the translation. Bad translations are caught by the type checker. - -This is where the heutagogic training loop becomes essential: the SLM gets better -at cross-system translation over time, learning from its own failures. - -**Layer 3: Ontology grounding via Description Logic provers** - -For the ontology side, use Description Logic reasoners (HermiT, ELK, Konclude) as -a bridge: -- User defines domain ontology in a visual editor (part of the proof pipeline) -- Ontology is checked by a DL reasoner for consistency -- Relevant ontological facts are extracted and encoded as prover axioms -- ECHIDNA dispatches the proof with these axioms available - -This doesn't solve the full problem but it handles the common case: "I have a domain -model, I want to prove properties about it." - -### The Honest Assessment - -**I don't know how to fully solve this.** The semantic gap between logics is a -research problem, not an engineering problem. Dedukti/Lambdapi comes closest but -it requires users to understand logical frameworks — which defeats the progressive -sophistication goal. - -The most promising path is the combination of: -1. Semantic typeclasses (narrow the problem to common mathematical structures) -2. SLM translation (handle the cases typeclasses don't cover) -3. Prover validation (catch translation errors) -4. Honest degradation (tell the user when a goal can't be faithfully translated - to a particular prover, rather than silently producing something wrong) - -This is Phase 12 for a reason. It's the hardest, it depends on everything else -working, and it may require research breakthroughs — not just engineering. - ---- - -## F. Summary - -| Question | Answer | -|----------|--------| -| What's working? | Elm architecture, typed domain model, test coverage, Tauri separation | -| What's failing? | ARIA gap, monolithic model, mixed UI/domain state, no schema versioning | -| What needs rethinking? | Rigid pane model, flat monologue, duplicated backend patterns | -| Big plan ordering? | Accessibility → Refactor → Interop → Visual → Syntax → Layouts → i18n → Collab → SLM → Notation | -| Closest competitor? | Why3 (dispatch) + Wolfram (experience) — but nothing combines all pieces | -| Feedback to other repos? | 10 concrete insights (Evangeliser, ECHIDNA API, VeriSimDB UX, Trustfile, Proven audit, Echidnabot, IDApTIK, DeepProbLog, fuzzy search, Pandoc) | -| Hardest unsolved problem? | Semantic translation between logics + ontology grounding — the bridge between notation and provers | - ---- - -## References - -- Why3: https://why3.lri.fr/ -- Dedukti: https://deducteam.github.io/ -- MMT: https://uniformal.github.io/ -- DOL: https://dol-omg.github.io/ -- Logipedia: https://logipedia.inria.fr/ -- Wolfram Language: https://www.wolfram.com/language/ -- Companion design documents in this directory diff --git a/docs/design/DESIGN-2026-03-01-vab-panel.adoc b/docs/design/DESIGN-2026-03-01-vab-panel.adoc new file mode 100644 index 00000000..8ce7cb3a --- /dev/null +++ b/docs/design/DESIGN-2026-03-01-vab-panel.adoc @@ -0,0 +1,233 @@ +== DESIGN-2026-03-01: VAB (Verified Assembly Building) Panel + +*Repository:* panll *Date:* 2026-03-01 *Author:* Jonathan D.A. Jewell +(hyperpolymath) *Status:* Implementation Complete + +=== Summary + +KSP VAB-inspired visual panel in PanLL for composing verified server +components from the proven-servers catalog (108 components). Users +browse components by category, add them to a virtual server rack, see +real-time dependency warnings, and enumerate what the assembled server +CAN and CANNOT do. + +=== Motivation + +The proven-servers project contains 108 formally verified Idris2 server +components (8 core primitives, 94 protocols, 6 connectors). To make this +library accessible and composable, we need a visual assembly tool that: + +[arabic] +. Presents all 108 components in an organised, browsable catalog +. Lets users compose server stacks by adding/removing components +. Validates dependencies in real-time (like KSP’s "`No engine!`" +warnings) +. Enumerates capabilities (what the assembled server can/cannot do) +. Follows the data-centre aesthetic of the PanLL environment + +=== Architecture + +==== Files Created + +[width="100%",cols="29%,40%,31%",options="header",] +|=== +|File |Purpose |Lines +|`+src/model/VabModel.res+` |State types (leaf, no deps) |~70 + +|`+src/core/VabCatalog.res+` |Hardcoded catalog of all 108 components +|~900 + +|`+src/core/VabEngine.res+` |Dependency checking + capability +computation |~200 + +|`+src/components/Vab.res+` |Main VAB component (TEA view) |~500 +|=== + +==== Files Modified + +[width="100%",cols="40%,60%",options="header",] +|=== +|File |Changes +|`+src/Model.res+` |Added `+include VabModel+`, `+vab: vabState+` field, +init state + +|`+src/Msg.res+` |Added `+vabMsg+` type (9 variants), `+Vab(vabMsg)+` in +unified msg + +|`+src/Update.res+` |Added `+updateVab+` sub-updater + +`+recomputeVabStatus+` helper + +|`+src/View.res+` |Added VAB overlay rendering (conditional on +vab.visible) + +|`+src/SubscriptionsFixed.res+` |Added Ctrl+Shift+V shortcut for VAB +toggle +|=== + +==== TEA Integration Pattern + +.... +User action (click category, add component, etc.) + -> Vab(vabMsg) dispatched + -> updateVab(model, vabMsg) called + -> For assembly changes: recomputeVabStatus(vab) called + -> VabEngine.checkDependencies(ids, catalog) -> warnings + -> VabEngine.computeCapabilities(ids, catalog, warnings) -> capabilities + -> New model returned + -> applyContractiles post-processing + -> View re-renders +.... + +=== Visual Design (KSP VAB-Inspired) + +.... ++================================================================+ +| [KSP-GREEN TOOLBAR] VAB | Server: "Untitled" [Clear] [Close] | ++==+===========================+=================================+ +|P | Component Grid | Server Rack (Assembly Area) | +|A | +------+ +------+ | +----+---+--+----------------+ | +|R | | httpd| | tls | | |bolt|[1]|G | proven-tls 443| | +|T | | :443 | | V | | |bolt|[2]|G | proven-httpd | | +|S | | 1U | | 0dep | | |bolt|[3]|G | proven-dbconn | | +| | +------+ +------+ | | | | | --- empty --- | | +| | +------+ +------+ | | | | | --- empty --- | | +|G | | grpc | | ws | | +----+---+--+----------------+ | +|R | |50051 | | V | | | +|E | | 1U | | 0dep | | WARNINGS | +|E | +------+ +------+ | !! Missing: proven-socket | +|N | | !~ No audit - ops not logged | +| | | | ++==+===========================+=================================+ +| GO/HOLD | V HTTP V DB X Email X Cache ! Audit V AI/NeuroS | ++================================================================+ +.... + +Key KSP visual elements: - Green gradient toolbar (top) — matches KSP’s +iconic green bar - Green sidebar category tabs (left) — like KSP’s part +category selector - Orange staging numbers [1] [2] [3] — KSP staging +system - Green/red LED indicators — hardware status lights - Bolt +decorations on rack rails — industrial mounting hardware - Orange accent +on selection and hover — KSP’s selection highlight - "`GO`"/"`HOLD`" +mission readiness indicator (bottom) — mission control style - +Capability badges: green=CAN, gray=CANNOT, orange=WARNING + +=== Component Categories (11) + +[width="100%",cols="25%,13%,16%,46%",options="header",] +|=== +|Category |Icon |Count |Example Components +|Core |C |8 |socket, frame, fsm, wire, compose, tls, config, audit + +|Network |N |12 |proxy, loadbalancer, vpn, firewall, socks, telnet + +|DNS |D |5 |dns, mdns, doh, dot, doq + +|Web |W |10 |httpd, ws, grpc, graphql, apiserver, wasm + +|IoT |I |7 |mqtt, coap, amqp, modbus, opcua, mcp + +|Email |E |5 |smtp, imap, pop3, lpd, odns + +|Security |S |14 |ssh-bastion, kerberos, radius, ldap, ids, zerotrust + +|Data |Dt |14 |dbserver, graphdb, cache, objectstore, nfs, git + +|App |A |14 |voip, xmpp, chat, gameserver, agentic, neurosym + +|Infra |If |13 |syslog, snmp, ntp, bgp, ospf, dhcp, container + +|Conn |Cn |6 |dbconn, cacheconn, storageconn, queueconn, authconn, +resolverconn +|=== + +*Total: 108 components* + +=== Dependency Rules + +[arabic] +. All protocols with ports need `+proven-socket+` +. All secure protocols recommend `+proven-tls+` +. Any assembly with 3+ components recommends `+proven-audit+` +. Any assembly with 3+ components recommends `+proven-config+` +. Port conflicts detected when two components share a port +. Components using secure ports (443, 993, 8443, 636) warn if no TLS + +=== Capability Categories (23) + +HTTP serving, Encryption (TLS), DNS resolution, Database queries, +Caching, Email (send), Email (receive), Authentication, Audit logging, +Load balancing, Proxying, Real-time messaging, File transfer, IoT +messaging, VPN/tunnelling, Container isolation, Monitoring, Intrusion +detection, AI/neurosymbolic, AI manifests (A2ML), K9 contractiles, +Internationalisation, Document formats. + +=== Colour Scheme (KSP VAB Aesthetic) + +The visual design closely mirrors KSP’s iconic Vehicle Assembly +Building: green toolbar and category tabs, orange selection accents, +industrial steel rack rails, staging indicators, bolt decorations, and +LED status lights. + +[width="100%",cols="30%,41%,29%",options="header",] +|=== +|Element |CSS / Colour |Purpose +|Toolbar |`+#4a7c40+` → `+#2d4e27+` gradient |KSP green toolbar bar + +|Category sidebar |`+#344f2e+` → `+#2a3f25+` gradient |KSP green part +tabs + +|Active category |`+#5a9e50+` → `+#4a8a42+` gradient |Bright KSP green + +|Selection accent |`+#e8721c+` (orange) |KSP orange highlight + +|Assembly rack bg |`+#141414+` with grid |Industrial hangar floor + +|Rack unit |`+#3a3a3a+` → `+#2e2e2e+` gradient |Brushed steel rack units + +|LED (ok) |`+#7cfc00+` → `+#3a8a2e+` radial |Green LED + +|LED (error) |`+#ff4444+` → `+#cc2222+` radial |Red LED (blinking) + +|Staging number |`+#e8721c+` → `+#cc5a10+` gradient |KSP orange stage +indicators + +|Verified tick |`+#5a9e50+` with glow |Green science-unlock style + +|Warning |`+#e8721c+` with shadow |Orange klaxon caution + +|Error |`+#cc3333+` with shadow |Red klaxon error + +|Status "`GO`" |`+#5a9e50+` |Green mission readiness + +|Status "`HOLD`" |`+#cc3333+` |Red mission hold + +|Bolt decorations |`+#666+` → `+#333+` radial |Rack mounting screws + +|Part card |`+#2e2e2e+` with `+#444+` border |KSP part picker cards + +|Port badge |`+#e8a050+` on `+rgba(232,114,28,0.15)+` |Orange port +indicators +|=== + +Custom CSS classes defined in `+src/styles/input.css+`: `+vab-toolbar+`, +`+vab-sidebar+`, `+vab-sidebar-btn+`, `+vab-sidebar-btn-active+`, +`+vab-rack+`, `+vab-rack-rails+`, `+vab-rack-unit+`, +`+vab-rack-unit-error+`, `+vab-rack-empty+`, `+vab-stage+`, +`+vab-part+`, `+vab-part-installed+`, `+vab-verified+`, `+vab-stats+`, +`+vab-warning-error+`, `+vab-warning-caution+`, `+vab-warning-info+`, +`+vab-cap-yes+`, `+vab-cap-no+`, `+vab-cap-warn+`, `+vab-led-green+`, +`+vab-led-red+`, `+vab-bolt+`. + +=== Keyboard Shortcuts + +* `+Ctrl+Shift+V+` — Toggle VAB panel visibility +* `+Escape+` — Close VAB panel (when open) + +=== Future Work + +* Drag-and-drop reordering of rack components +* Server template presets (e.g. "`Web Stack`", "`Mail Server`", "`IoT +Gateway`") +* Export assembled server as proven-servers compose script +* Tauri backend integration for actually building server binaries +* PanLL VAB as a standalone panel mode (not just overlay) diff --git a/docs/design/DESIGN-2026-03-01-vab-panel.md b/docs/design/DESIGN-2026-03-01-vab-panel.md deleted file mode 100644 index 2c6d3cd6..00000000 --- a/docs/design/DESIGN-2026-03-01-vab-panel.md +++ /dev/null @@ -1,176 +0,0 @@ -# DESIGN-2026-03-01: VAB (Verified Assembly Building) Panel - -**Repository:** panll -**Date:** 2026-03-01 -**Author:** Jonathan D.A. Jewell (hyperpolymath) -**Status:** Implementation Complete - -## Summary - -KSP VAB-inspired visual panel in PanLL for composing verified server -components from the proven-servers catalog (108 components). Users browse -components by category, add them to a virtual server rack, see real-time -dependency warnings, and enumerate what the assembled server CAN and CANNOT do. - -## Motivation - -The proven-servers project contains 108 formally verified Idris2 server -components (8 core primitives, 94 protocols, 6 connectors). To make this -library accessible and composable, we need a visual assembly tool that: - -1. Presents all 108 components in an organised, browsable catalog -2. Lets users compose server stacks by adding/removing components -3. Validates dependencies in real-time (like KSP's "No engine!" warnings) -4. Enumerates capabilities (what the assembled server can/cannot do) -5. Follows the data-centre aesthetic of the PanLL environment - -## Architecture - -### Files Created - -| File | Purpose | Lines | -|------|---------|-------| -| `src/model/VabModel.res` | State types (leaf, no deps) | ~70 | -| `src/core/VabCatalog.res` | Hardcoded catalog of all 108 components | ~900 | -| `src/core/VabEngine.res` | Dependency checking + capability computation | ~200 | -| `src/components/Vab.res` | Main VAB component (TEA view) | ~500 | - -### Files Modified - -| File | Changes | -|------|---------| -| `src/Model.res` | Added `include VabModel`, `vab: vabState` field, init state | -| `src/Msg.res` | Added `vabMsg` type (9 variants), `Vab(vabMsg)` in unified msg | -| `src/Update.res` | Added `updateVab` sub-updater + `recomputeVabStatus` helper | -| `src/View.res` | Added VAB overlay rendering (conditional on vab.visible) | -| `src/SubscriptionsFixed.res` | Added Ctrl+Shift+V shortcut for VAB toggle | - -### TEA Integration Pattern - -``` -User action (click category, add component, etc.) - -> Vab(vabMsg) dispatched - -> updateVab(model, vabMsg) called - -> For assembly changes: recomputeVabStatus(vab) called - -> VabEngine.checkDependencies(ids, catalog) -> warnings - -> VabEngine.computeCapabilities(ids, catalog, warnings) -> capabilities - -> New model returned - -> applyContractiles post-processing - -> View re-renders -``` - -## Visual Design (KSP VAB-Inspired) - -``` -+================================================================+ -| [KSP-GREEN TOOLBAR] VAB | Server: "Untitled" [Clear] [Close] | -+==+===========================+=================================+ -|P | Component Grid | Server Rack (Assembly Area) | -|A | +------+ +------+ | +----+---+--+----------------+ | -|R | | httpd| | tls | | |bolt|[1]|G | proven-tls 443| | -|T | | :443 | | V | | |bolt|[2]|G | proven-httpd | | -|S | | 1U | | 0dep | | |bolt|[3]|G | proven-dbconn | | -| | +------+ +------+ | | | | | --- empty --- | | -| | +------+ +------+ | | | | | --- empty --- | | -|G | | grpc | | ws | | +----+---+--+----------------+ | -|R | |50051 | | V | | | -|E | | 1U | | 0dep | | WARNINGS | -|E | +------+ +------+ | !! Missing: proven-socket | -|N | | !~ No audit - ops not logged | -| | | | -+==+===========================+=================================+ -| GO/HOLD | V HTTP V DB X Email X Cache ! Audit V AI/NeuroS | -+================================================================+ -``` - -Key KSP visual elements: -- Green gradient toolbar (top) — matches KSP's iconic green bar -- Green sidebar category tabs (left) — like KSP's part category selector -- Orange staging numbers [1] [2] [3] — KSP staging system -- Green/red LED indicators — hardware status lights -- Bolt decorations on rack rails — industrial mounting hardware -- Orange accent on selection and hover — KSP's selection highlight -- "GO"/"HOLD" mission readiness indicator (bottom) — mission control style -- Capability badges: green=CAN, gray=CANNOT, orange=WARNING - -## Component Categories (11) - -| Category | Icon | Count | Example Components | -|----------|------|-------|--------------------| -| Core | C | 8 | socket, frame, fsm, wire, compose, tls, config, audit | -| Network | N | 12 | proxy, loadbalancer, vpn, firewall, socks, telnet | -| DNS | D | 5 | dns, mdns, doh, dot, doq | -| Web | W | 10 | httpd, ws, grpc, graphql, apiserver, wasm | -| IoT | I | 7 | mqtt, coap, amqp, modbus, opcua, mcp | -| Email | E | 5 | smtp, imap, pop3, lpd, odns | -| Security | S | 14 | ssh-bastion, kerberos, radius, ldap, ids, zerotrust | -| Data | Dt | 14 | dbserver, graphdb, cache, objectstore, nfs, git | -| App | A | 14 | voip, xmpp, chat, gameserver, agentic, neurosym | -| Infra | If | 13 | syslog, snmp, ntp, bgp, ospf, dhcp, container | -| Conn | Cn | 6 | dbconn, cacheconn, storageconn, queueconn, authconn, resolverconn | - -**Total: 108 components** - -## Dependency Rules - -1. All protocols with ports need `proven-socket` -2. All secure protocols recommend `proven-tls` -3. Any assembly with 3+ components recommends `proven-audit` -4. Any assembly with 3+ components recommends `proven-config` -5. Port conflicts detected when two components share a port -6. Components using secure ports (443, 993, 8443, 636) warn if no TLS - -## Capability Categories (23) - -HTTP serving, Encryption (TLS), DNS resolution, Database queries, Caching, -Email (send), Email (receive), Authentication, Audit logging, Load balancing, -Proxying, Real-time messaging, File transfer, IoT messaging, VPN/tunnelling, -Container isolation, Monitoring, Intrusion detection, AI/neurosymbolic, -AI manifests (A2ML), K9 contractiles, Internationalisation, Document formats. - -## Colour Scheme (KSP VAB Aesthetic) - -The visual design closely mirrors KSP's iconic Vehicle Assembly Building: -green toolbar and category tabs, orange selection accents, industrial steel -rack rails, staging indicators, bolt decorations, and LED status lights. - -| Element | CSS / Colour | Purpose | -|---------|-------------|---------| -| Toolbar | `#4a7c40` → `#2d4e27` gradient | KSP green toolbar bar | -| Category sidebar | `#344f2e` → `#2a3f25` gradient | KSP green part tabs | -| Active category | `#5a9e50` → `#4a8a42` gradient | Bright KSP green | -| Selection accent | `#e8721c` (orange) | KSP orange highlight | -| Assembly rack bg | `#141414` with grid | Industrial hangar floor | -| Rack unit | `#3a3a3a` → `#2e2e2e` gradient | Brushed steel rack units | -| LED (ok) | `#7cfc00` → `#3a8a2e` radial | Green LED | -| LED (error) | `#ff4444` → `#cc2222` radial | Red LED (blinking) | -| Staging number | `#e8721c` → `#cc5a10` gradient | KSP orange stage indicators | -| Verified tick | `#5a9e50` with glow | Green science-unlock style | -| Warning | `#e8721c` with shadow | Orange klaxon caution | -| Error | `#cc3333` with shadow | Red klaxon error | -| Status "GO" | `#5a9e50` | Green mission readiness | -| Status "HOLD" | `#cc3333` | Red mission hold | -| Bolt decorations | `#666` → `#333` radial | Rack mounting screws | -| Part card | `#2e2e2e` with `#444` border | KSP part picker cards | -| Port badge | `#e8a050` on `rgba(232,114,28,0.15)` | Orange port indicators | - -Custom CSS classes defined in `src/styles/input.css`: -`vab-toolbar`, `vab-sidebar`, `vab-sidebar-btn`, `vab-sidebar-btn-active`, -`vab-rack`, `vab-rack-rails`, `vab-rack-unit`, `vab-rack-unit-error`, -`vab-rack-empty`, `vab-stage`, `vab-part`, `vab-part-installed`, -`vab-verified`, `vab-stats`, `vab-warning-error`, `vab-warning-caution`, -`vab-warning-info`, `vab-cap-yes`, `vab-cap-no`, `vab-cap-warn`, -`vab-led-green`, `vab-led-red`, `vab-bolt`. - -## Keyboard Shortcuts - -- `Ctrl+Shift+V` — Toggle VAB panel visibility -- `Escape` — Close VAB panel (when open) - -## Future Work - -- Drag-and-drop reordering of rack components -- Server template presets (e.g. "Web Stack", "Mail Server", "IoT Gateway") -- Export assembled server as proven-servers compose script -- Tauri backend integration for actually building server binaries -- PanLL VAB as a standalone panel mode (not just overlay) diff --git a/docs/design/DESIGN-2026-03-08-idaptik-ensaid.adoc b/docs/design/DESIGN-2026-03-08-idaptik-ensaid.adoc new file mode 100644 index 00000000..9dfb89e0 --- /dev/null +++ b/docs/design/DESIGN-2026-03-08-idaptik-ensaid.adoc @@ -0,0 +1,631 @@ +== PanLL as eNSAID for IDApTIK Development + +*Date*: 2026-03-08 *Author*: Jonathan D.A. Jewell +j.d.a.jewell@open.ac.uk *Status*: Design (MuSCoCA-classified) + +=== Overview + +This document designs PanLL as an *eNSAID* (Environment for NeSy-Agentic +Integrated Development) tailored for IDApTIK game development — a +collaborative parent-child workbench where Jonathan and his son can +build, test, debug, visualise, and evolve the IDApixiTIK game together. + +The key insight: IDApTIK is a *reversible-computation stealth puzzle +game* with a VM, multiplayer sync server, coprocessor system, device +network topology, and formal verification layer. PanLL’s three-panel +neurosymbolic model maps directly onto this: + +[width="100%",cols="44%,56%",options="header",] +|=== +|PanLL Panel |IDApTIK Mapping +|*Panel-L* (Symbolic) |VM instruction constraints, level rules, device +defence flags, protocol specs + +|*Panel-N* (Neural) |ECHIDNA proof advisor for VM correctness, +AI-assisted level design, NeSy reasoning + +|*Panel-W* (World) |Game preview, network topology view, device +dashboard, telemetry +|=== + +''''' + +=== The IDApTIK Panel Suite + +==== New Panels (8 IDApTIK-specific) + +These panels form the *IDApTIK Development Kit (IDK)* — a PanLL panel +bundle that transforms the eNSAID into a game development environment. + +''''' + +==== Panel 1: Valence Shell (MUST) + +*ID*: `+PanelValenceShell+` *Kind*: terminal *Icon*: `+terminal-square+` +*Priority*: MUST — first thing to build + +Embedded Valence shell running inside a PanLL panel. This is the primary +interface for running Claude Code, build commands, git operations, and +interactive development. + +*Features*: - Full Valence shell (formally verified reversible +filesystem ops) - PTY allocation via Tauri shell plugin +(`+@tauri-apps/plugin-shell+`) - Claude Code integration — run +`+claude+` CLI directly in the panel - Session recording — capture +terminal sessions as `+.cast+` files (asciinema format) - Screenshot +terminal state to Capture panel - Share terminal sessions via export +(JSON, cast, HTML replay) - Split view: multiple terminal instances side +by side - Command palette with IDApTIK-aware completions +(`+deno task dev+`, `+deno task res:build+`, etc.) - Reversible command +history with Valence’s MAA audit trail - Alkahest transmuter integration +for format conversions + +*Panel-L integration*: Display active filesystem constraints (watched +paths, undo checkpoints) *Panel-N integration*: AI command suggestions +based on current context *Panel-W integration*: Terminal output feeds +watcher events + +*Collaborative*: Both parent and child see the same terminal (shared +session mode). Child can type commands, parent can review before +execution (approval gate). + +*Backend*: Tauri shell plugin for PTY, Valence shell binary for +reversible ops. + +''''' + +==== Panel 2: Game Preview (MUST) + +*ID*: `+PanelGamePreview+` *Kind*: viewer *Icon*: `+gamepad-2+` + +Live game preview embedded in PanLL via iframe or Tauri webview. + +*Features*: - Embedded Vite dev server output (port 8080) - Hot-reload — +changes in ReScript files reflect immediately - Pause/resume game loop +for inspection - Frame-by-frame stepping (connect to GameLoop.res tick) +- FPS counter, render stats overlay - Device interaction log (which +devices the player touched) - Screenshot current game frame → Capture +panel - Record gameplay clips (WebM via MediaRecorder API) - Overlay +toggle: show collision boxes, network topology, guard patrol paths - +Zoom and pan for level inspection + +*Panel-L integration*: Display active level constraints (LevelConfig.res +flags) *Panel-N integration*: AI commentary on gameplay patterns, +difficulty estimation *Panel-W integration*: Feeds game events to world +canvas + +*Collaborative*: Parent and child each see the preview; multiplayer mode +shows both players simultaneously (asymmetric co-op view). + +''''' + +==== Panel 3: VM Inspector (MUST) + +*ID*: `+PanelVmInspector+` *Kind*: viewer *Icon*: `+cpu+` + +Visual debugger for the reversible VM — the core computation engine. + +*Features*: - Stack visualisation (push/pop animated) - Memory cells +displayed as grid with highlighting on read/write - Instruction pointer +with assembly listing - Step forward / step backward (reversible!) - +Breakpoints on instructions, memory addresses, stack depth - Execution +timeline scrubber — drag to any point in execution history - Subroutine +call graph (SubroutineRegistry visualisation) - Port I/O monitoring +(SEND/RECV buffers) - Multi-VM view for multiplayer (each player’s VM +side by side) - Instruction statistics: most-executed, cycle count, tier +usage - Export VM state snapshot (JSON) + +*Panel-L integration*: Display proof obligations for VM instruction +correctness *Panel-N integration*: ECHIDNA verifies instruction +reversibility proofs *Panel-W integration*: VM state feeds telemetry +dashboard + +*Collaborative*: Child can step through VM execution while parent +explains the instruction semantics. "`What happens if we SWAP here?`" + +''''' + +==== Panel 4: Network Topology (SHOULD) + +*ID*: `+PanelNetworkTopology+` *Kind*: viewer *Icon*: `+network+` + +Visual map of the in-game network — devices, connections, zones, +security levels. + +*Features*: - Force-directed graph layout of network devices - +Colour-coded zones: LAN (green), VLAN (blue), External (red) - Device +icons matching in-game types (laptop, router, camera, firewall, PBX) - +Security level indicators (Open/Weak/Medium/Strong) - Live packet flow +animation (traceroute visualisation) - Click device → open device GUI in +Game Preview panel - Defence flag badges on devices (tamperProof, decoy, +canary, killSwitch, etc.) - DNS resolution tree (Atlas 8.8.8.8, Nexus +1.1.1.1) - SSH connection paths highlighted - Drag-to-rearrange topology +for level design - Export topology as SVG/PNG + +*Panel-L integration*: Constraint editor for network rules (zone access, +firewall rules) *Panel-N integration*: Suggest network topology +improvements, detect unreachable devices *Panel-W integration*: Overlay +on world canvas for spatial context + +''''' + +==== Panel 5: Level Architect (SHOULD) + +*ID*: `+PanelLevelArchitect+` *Kind*: builder *Icon*: `+map+` + +Visual level design tool — the PanLL version of IDApTIK-UMS. + +*Features*: - Drag-and-drop device placement on level grid - Guard +patrol path editor (waypoint-based) - Spawn point configuration - +Defence flag toggles per device (11 flags from LevelConfig.res) - Alert +threshold sliders - Asset browser (from AssetPack manifest) - Level +validation: run VM simulation to check solvability - Companion placement +(Moletaire start position, food items) - Level export to LevelConfig.res +format - Level import from existing configs - Undo/redo with Valence +checkpoint integration - Side-by-side: edit left, preview right + +*Panel-L integration*: Formal constraints on level design (min exits, +device connectivity) *Panel-N integration*: AI difficulty estimation, +auto-balance suggestions *Panel-W integration*: Level metrics dashboard +(estimated completion time, paths) + +*Collaborative*: Parent designs level structure, child places devices +and tests. + +''''' + +==== Panel 6: Coprocessor Dashboard (SHOULD) + +*ID*: `+PanelCoprocessors+` *Kind*: viewer *Icon*: `+chip+` + +Monitor and inspect the 3 coprocessor backends (Compute, Security, I/O). + +*Features*: - Real-time coprocessor call log - Backend health status +(Maths, Vector, Tensor, Physics, Crypto, Neural, Quantum, Audio, +Graphics, I/O) - Call frequency heatmap - Performance metrics per +backend - Input/output inspection for individual calls - +CoprocessorManager dispatch log - Backend toggle (enable/disable for +testing) + +*Panel-L integration*: Coprocessor contracts (expected input ranges, +output guarantees) *Panel-N integration*: Anomaly detection on +coprocessor usage patterns *Panel-W integration*: Performance metrics +feed world canvas + +''''' + +==== Panel 7: Multiplayer Monitor (COULD) + +*ID*: `+PanelMultiplayer+` *Kind*: viewer *Icon*: `+users+` + +Monitor the Elixir/Phoenix sync server and multiplayer state. + +*Features*: - WebSocket connection status - Phoenix channel +subscriptions - Player state diff (Hacker vs Observer roles) - +VMMessageBus traffic monitor - Lamport clock visualisation (causal +ordering) - Device lock status (who’s editing which device) - Latency +graph (client ↔ server round-trip) - Sync server process tree (Horde +distributed supervisor) - ETS cache inspection - Reconnection test +trigger + +*Panel-L integration*: Protocol constraints from proven-servers +gameserver spec *Panel-N integration*: Predict desync risk from Lamport +clock drift *Panel-W integration*: Multiplayer health feeds world canvas + +''''' + +==== Panel 8: DLC Workshop (COULD) + +*ID*: `+PanelDlcWorkshop+` *Kind*: builder *Icon*: `+puzzle+` + +Create, test, and package DLC puzzle packs. + +*Features*: - Puzzle editor with VM instruction composer - Test runner +for puzzle solutions (42-test suite integration) - Difficulty +classification - Asset bundling for DLC distribution - Import/export +puzzle packs - Puzzle chain editor (sequence of related puzzles) + +*Panel-L integration*: Puzzle solvability proofs (ECHIDNA checks +reversibility) *Panel-N integration*: AI-generated puzzle suggestions +based on difficulty curve *Panel-W integration*: Puzzle analytics +(completion rates, hint usage) + +''''' + +=== Core eNSAID Features for IDApTIK + +==== TyPELL (Type-Level Intelligence) + +TyPELL operates through Panel-L’s constraint layer: + +[width="100%",cols="30%,70%",options="header",] +|=== +|Feature |IDApTIK Application +|*Type checking* |Validate LevelConfig.res against expected schema + +|*Exhaustiveness* |Ensure all DeviceType variants handled in +DeviceFactory + +|*Constraint propagation* |If guard count > 5, alert threshold must be ≥ +Medium + +|*Temporal types* |VM instruction sequences must be reversible +(provable) +|=== + +==== ECHIDNA (Theorem Prover Integration) + +Panel-N’s ECHIDNA advisor applied to game development: + +[width="100%",cols="53%,47%",options="header",] +|=== +|Proof Obligation |What It Checks +|VM reversibility |`+undo(do(instruction, state)) == state+` for all 23 +instructions + +|Level solvability |At least one path from spawn to objective exists + +|Device reachability |All networked devices can reach gateway + +|Defence consistency |`+tamperProof+` and `+decoy+` are mutually +exclusive + +|Save/load roundtrip |`+deserialize(serialize(gameState)) == gameState+` + +|Coprocessor safety |Input ranges produce valid outputs (no NaN, no +overflow) +|=== + +Trust Level applied: game builds only with Level 3+ proofs (multiple +solver agreement). + +==== NeSy (Neurosymbolic Reasoning) + +The binary star model applied to IDApTIK: + +* *Symbolic star* (Panel-L): VM instruction rules, network topology +constraints, level design rules +* *Neural star* (Panel-N): AI-assisted level generation, difficulty +estimation, playtest analysis +* *Barycentre* (Panel-W): Where symbolic proofs meet neural suggestions +— the game preview with overlays + +==== Agentic Features + +BoJ cartridge integration for autonomous development workflows: + +[cols=",",options="header",] +|=== +|Cartridge |IDApTIK Use +|`+database-mcp+` |Save/load game state to VeriSimDB +|`+git-mcp+` |Version control from within PanLL +|`+container-mcp+` |Build and deploy game containers +|`+observe-mcp+` |Game telemetry and performance monitoring +|`+nesy-mcp+` |Neurosymbolic reasoning for level design +|`+agent-mcp+` |Automated playtest workflows +|`+proof-mcp+` |ECHIDNA proof submission from BoJ +|=== + +''''' + +=== External Portfolio Integration + +==== panic-attack (Existing Panel) + +Already wired. For IDApTIK: scan game code for unsafe patterns, command +injection in network simulation, ReScript-specific weak points. + +==== Mass Panic (Existing Panel) + +Already wired. For IDApTIK: batch scan all monorepo subdirectories +(src/, vm/, shared/, dlc/, sync-server/). + +==== VAB (Existing Panel) + +Already wired. For IDApTIK: compose the game’s server stack from +proven-servers components (gameserver, websocket, dns, firewall +protocols). + +==== Databases (Existing Panel) + +Already wired. For IDApTIK: VeriSimDB for game telemetry persistence, +drift detection on game state, entity browser for level objects. + +==== Capture (Existing Panel) + +Already wired. Critical for collaborative use — screenshot game state, +record development sessions, compare before/after level changes. + +==== AI Panel (Existing) + +Already wired. For IDApTIK: Claude integration for code assistance, +level design suggestions, debugging help. This is the AI conversation +panel complementing the Valence Shell’s Claude CLI. + +''''' + +=== Collaborative Features (Parent-Child) + +==== Shared Session Mode + +* Both users see the same PanLL instance (same Tauri window or +screen-shared) +* Valence Shell has "`approval gate`": child types command, parent +approves +* Game Preview shows both players in multiplayer mode +* VM Inspector supports "`explain mode`": step-by-step with annotations + +==== Recording and Sharing + +* *Session recording*: Valence Shell records terminal sessions +(asciinema .cast) +* *Gameplay recording*: Game Preview records WebM clips +* *Screenshot*: Any panel → Capture panel → PNG export +* *Comparison views*: Capture panel’s diff mode shows before/after +changes +* *Share*: Export session bundles (terminal + gameplay + screenshots) as +ZIP + +==== Visualisation + +* *VM execution timeline*: Scrubber showing instruction flow with +undo/redo +* *Network topology graph*: Force-directed device map with live traffic +* *Coprocessor heatmap*: Which backends are hot during gameplay +* *Level difficulty map*: Colour overlay showing hard/easy areas +* *Orbital drift aura*: Ambient visual showing symbolic/neural co-orbit +health + +''''' + +=== Watcher Integration + +The existing watcher infrastructure feeds IDApTIK-specific events: + +[width="100%",cols="43%,57%",options="header",] +|=== +|Watch Path |Panel Reaction +|`+src/**/*.res+` |Game Preview hot-reloads, panic-attack re-scans + +|`+vm/lib/ocaml/**/*.res+` |VM Inspector reloads instruction set, +ECHIDNA re-verifies + +|`+shared/src/**/*.res+` |Coprocessor Dashboard refreshes backend status + +|`+dlc/**/*.res+` |DLC Workshop re-runs puzzle tests + +|`+sync-server/**/*.ex+` |Multiplayer Monitor checks sync server health + +|`+raw-assets/**/*+` |Game Preview triggers AssetPack rebuild + +|`+src/app/screens/LevelConfig.res+` |Level Architect reloads level +definitions +|=== + +''''' + +=== MuSCoCA Classification + +==== MUST (Minimum Viable eNSAID) + +[arabic] +. *Valence Shell panel* — embedded terminal with Claude Code, session +recording, reversible ops +. *Game Preview panel* — live iframe of Vite dev server with hot-reload +. *VM Inspector panel* — visual debugger with step forward/backward +. *Watcher integration* — file change events feed all IDApTIK panels +. *Panel registration* — 8 new panel IDs in PanelSwitcherModel.res + +PanelRegistry.res +. *Model/Msg/Update wiring* — TEA integration for all MUST panels + +==== SHOULD (Full Development Experience) + +[arabic, start=7] +. *Network Topology panel* — force-directed graph of in-game network +. *Level Architect panel* — visual level editor (PanLL version of UMS) +. *Coprocessor Dashboard* — monitor compute/security/IO backends +. *Shared session mode* — approval gate for child commands +. *ECHIDNA proofs for VM* — reversibility verification in Panel-N +. *BoJ cartridge integration* — database-mcp, git-mcp for dev workflows +. *Gameplay recording* — WebM capture in Game Preview + +==== COULD (Enhanced Experience) + +[arabic, start=14] +. *Multiplayer Monitor* — Phoenix channel inspector +. *DLC Workshop* — puzzle editor and test runner +. *Level difficulty estimator* — AI-powered analysis in Panel-N +. *Coprocessor anomaly detection* — NeSy reasoning on usage patterns +. *VM execution timeline* — full scrubber with undo/redo visualisation +. *Asset browser* — visual asset picker integrated with Level Architect +. *Export session bundles* — ZIP of terminal + gameplay + screenshots + +==== Corrective (Fix Existing Issues) + +[arabic, start=21] +. *Watcher debounce tuning* — 500ms default may be too slow for game dev +hot-reload +. *Panel-N OODA cycle* — ensure agency phase tracking works with +game-specific proofs +. *Capture panel format* — add WebM and asciinema .cast alongside +existing PNG +. *Anti-Crash for game events* — validate game state transitions through +circuit breaker + +==== Adaptive (Respond to Change) + +[arabic, start=25] +. *ReScript 13 migration panel* — when staging migration lands, track it +in PanLL +. *Multi-VM networking* — when VM Tier 5 lands, add cross-VM +visualisation +. *VeriSimDB temporal mode* — when per-level toggle ships, integrate +with Level Architect +. *Tauri 2 mobile* — adapt panels for tablet use (child on iPad, parent +on desktop) + +==== Perfective (Polish and Optimise) + +[arabic, start=29] +. *Panel transitions* — smooth animations between IDApTIK panels +. *Keyboard shortcuts* — game-dev-specific bindings (F5=run, +F9=breakpoint, F10=step) +. *Dark Start IDApTIK theme* — binary star animation with game +characters +. *Accessibility* — screen reader support for VM Inspector, colour-blind +mode for topology +. *Performance* — lazy-load IDApTIK panels only when IDApTIK repo is +loaded +. *Panel presets* — "`IDApTIK Dev`" workspace preset with recommended +panel arrangement + +''''' + +=== Recommended Panel Arrangement: IDApTIK Dev Mode + +.... +┌─────────────────────────────────────────────────────────────┐ +│ Panel Bar (vertical, left) │ +│ ┌──────────┬──────────────────────┬───────────────────────┐ │ +│ │ Panel-L │ Panel-N │ Panel-W │ │ +│ │ Level │ ECHIDNA │ Game Preview │ │ +│ │ Rules │ VM Proofs │ (live iframe) │ │ +│ │ │ │ │ │ +│ │ Device │ AI Commentary │ ┌─────────────┐ │ │ +│ │ Flags │ │ │ Network │ │ │ +│ │ │ Trust Level: │ │ Topology │ │ │ +│ │ Network │ ████ L3 │ │ Overlay │ │ │ +│ │ Constr. │ │ └─────────────┘ │ │ +│ ├──────────┴──────────────────────┴───────────────────────┤ │ +│ │ Valence Shell (bottom dock) │ │ +│ │ $ deno task dev │ │ +│ │ $ claude "help me add a new device type" │ │ +│ │ [Recording ●] [Share] [Screenshot] [Approval Gate: ON] │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ Status Bar: IDApTIK v0.1.0 | ReScript 12.1.0 | 0 errors │ +└─────────────────────────────────────────────────────────────┘ +.... + +''''' + +=== Implementation Order + +==== Phase 1: Shell First (Week 1-2) + +[arabic] +. Add `+PanelValenceShell+` to PanelSwitcherModel.res +. Create ValenceShellModel.res, ValenceShellMsg.res +. Wire PTY via `+@tauri-apps/plugin-shell+` +. Basic terminal emulator (xterm.js via Tauri webview) +. Claude Code launch command +. Session recording (asciinema format) + +==== Phase 2: Game Preview (Week 2-3) + +[arabic] +. Add `+PanelGamePreview+` to registry +. Embed Vite dev server output in iframe/webview +. Hot-reload integration with watcher +. FPS overlay and render stats +. Screenshot to Capture panel + +==== Phase 3: VM Inspector (Week 3-4) + +[arabic] +. Add `+PanelVmInspector+` to registry +. Connect to VM state via Tauri command bridge +. Stack and memory visualisation +. Step forward/backward controls +. Execution timeline scrubber + +==== Phase 4: Network + Level Tools (Week 5-6) + +[arabic] +. Network Topology panel (force-directed graph) +. Level Architect panel (device placement) +. Connect both to LevelConfig.res + +==== Phase 5: Collaborative Features (Week 7-8) + +[arabic] +. Shared session mode +. Approval gate for Valence Shell +. Recording and sharing infrastructure +. Workspace preset for "`IDApTIK Dev Mode`" + +''''' + +=== Technical Notes + +==== Panel Registration Pattern + +Each new panel requires: 1. `+PanelSwitcherModel.res+` — add variant to +`+panelId+` 2. `+PanelRegistry.res+` — add `+panelMeta+` entry 3. +`+src/model/XxxModel.res+` — domain types 4. `+src/components/Xxx.res+` +— view function 5. `+Model.res+` — `+include XxxModel+` 6. `+Msg.res+` — +add message type + variants 7. `+Update.res+` — add pattern match cases +8. `+View.res+` — add to `+renderActivePanel+` dispatch + +==== Terminal Emulator Options + +* *xterm.js* — industry standard, WebGL renderer, accessible +* Loaded via Tauri webview, communicates with Valence shell binary via +PTY +* Alternative: raw ANSI rendering in Tea_Html (simpler but less capable) + +==== Game Preview Embedding + +* Tauri supports multiple webviews — one for PanLL, one for game preview +* Communication via Tauri event bus (not postMessage) +* Game preview webview loads `+http://localhost:8080+` (Vite dev server) + +==== VM State Bridge + +* VM runs in game’s Vite webview +* Expose VM state via global `+window.__IDAPTIK_VM_STATE__+` +* PanLL reads via Tauri inter-webview messaging +* Or: VM state serialised to file, watcher picks it up (simpler, +decoupled) + +''''' + +=== Simulation, Emulation, and Beyond + +==== Simulation Mode + +Run the game logic without rendering — useful for: - Automated +playtesting (agent-mcp runs through levels) - Performance profiling (how +fast can the VM execute 10k instructions?) - Puzzle solvability checking +(brute-force all SWAP/ADD sequences) + +==== Emulation Mode + +Run the VM in a sandboxed PanLL panel without the full game: - Test +individual instructions - Compose subroutines - Verify reversibility +interactively - Educational: "`Here’s how XOR works`" with animated +visualisation + +==== Preview Mode + +Live game preview with overlays — the standard development view. + +==== Watch Mode + +Passive monitoring — watcher feeds events, panels update, no interaction +required. Good for "`leave it running while we code`" workflows. + +''''' + +=== Summary + +PanLL becomes the *mission control for IDApTIK development* by adding 8 +game-specific panels to the existing 22-panel suite. The Valence Shell +is the foundation — it gives parent and child a shared, recorded, +reversible terminal with Claude Code integration. The Game Preview, VM +Inspector, and Network Topology panels provide the visual development +experience. ECHIDNA proves VM correctness, BoJ cartridges automate +workflows, and panic-attack keeps the codebase secure. + +The MuSCoCA classification ensures we build the most valuable panels +first (Shell, Preview, VM Inspector) while planning for collaborative +features, multiplayer monitoring, and DLC creation tools. diff --git a/docs/design/DESIGN-2026-03-08-idaptik-ensaid.md b/docs/design/DESIGN-2026-03-08-idaptik-ensaid.md deleted file mode 100644 index 0b9e96a9..00000000 --- a/docs/design/DESIGN-2026-03-08-idaptik-ensaid.md +++ /dev/null @@ -1,587 +0,0 @@ -# PanLL as eNSAID for IDApTIK Development - -**Date**: 2026-03-08 -**Author**: Jonathan D.A. Jewell -**Status**: Design (MuSCoCA-classified) - -## Overview - -This document designs PanLL as an **eNSAID** (Environment for NeSy-Agentic -Integrated Development) tailored for IDApTIK game development — a collaborative -parent-child workbench where Jonathan and his son can build, test, debug, -visualise, and evolve the IDApixiTIK game together. - -The key insight: IDApTIK is a **reversible-computation stealth puzzle game** -with a VM, multiplayer sync server, coprocessor system, device network topology, -and formal verification layer. PanLL's three-panel neurosymbolic model maps -directly onto this: - -| PanLL Panel | IDApTIK Mapping | -|-------------|-----------------| -| **Panel-L** (Symbolic) | VM instruction constraints, level rules, device defence flags, protocol specs | -| **Panel-N** (Neural) | ECHIDNA proof advisor for VM correctness, AI-assisted level design, NeSy reasoning | -| **Panel-W** (World) | Game preview, network topology view, device dashboard, telemetry | - ---- - -## The IDApTIK Panel Suite - -### New Panels (8 IDApTIK-specific) - -These panels form the **IDApTIK Development Kit (IDK)** — a PanLL panel bundle -that transforms the eNSAID into a game development environment. - ---- - -### Panel 1: Valence Shell (MUST) - -**ID**: `PanelValenceShell` -**Kind**: terminal -**Icon**: `terminal-square` -**Priority**: MUST — first thing to build - -Embedded Valence shell running inside a PanLL panel. This is the primary -interface for running Claude Code, build commands, git operations, and -interactive development. - -**Features**: -- Full Valence shell (formally verified reversible filesystem ops) -- PTY allocation via Tauri shell plugin (`@tauri-apps/plugin-shell`) -- Claude Code integration — run `claude` CLI directly in the panel -- Session recording — capture terminal sessions as `.cast` files (asciinema format) -- Screenshot terminal state to Capture panel -- Share terminal sessions via export (JSON, cast, HTML replay) -- Split view: multiple terminal instances side by side -- Command palette with IDApTIK-aware completions (`deno task dev`, `deno task res:build`, etc.) -- Reversible command history with Valence's MAA audit trail -- Alkahest transmuter integration for format conversions - -**Panel-L integration**: Display active filesystem constraints (watched paths, undo checkpoints) -**Panel-N integration**: AI command suggestions based on current context -**Panel-W integration**: Terminal output feeds watcher events - -**Collaborative**: Both parent and child see the same terminal (shared session mode). -Child can type commands, parent can review before execution (approval gate). - -**Backend**: Tauri shell plugin for PTY, Valence shell binary for reversible ops. - ---- - -### Panel 2: Game Preview (MUST) - -**ID**: `PanelGamePreview` -**Kind**: viewer -**Icon**: `gamepad-2` - -Live game preview embedded in PanLL via iframe or Tauri webview. - -**Features**: -- Embedded Vite dev server output (port 8080) -- Hot-reload — changes in ReScript files reflect immediately -- Pause/resume game loop for inspection -- Frame-by-frame stepping (connect to GameLoop.res tick) -- FPS counter, render stats overlay -- Device interaction log (which devices the player touched) -- Screenshot current game frame → Capture panel -- Record gameplay clips (WebM via MediaRecorder API) -- Overlay toggle: show collision boxes, network topology, guard patrol paths -- Zoom and pan for level inspection - -**Panel-L integration**: Display active level constraints (LevelConfig.res flags) -**Panel-N integration**: AI commentary on gameplay patterns, difficulty estimation -**Panel-W integration**: Feeds game events to world canvas - -**Collaborative**: Parent and child each see the preview; multiplayer mode shows -both players simultaneously (asymmetric co-op view). - ---- - -### Panel 3: VM Inspector (MUST) - -**ID**: `PanelVmInspector` -**Kind**: viewer -**Icon**: `cpu` - -Visual debugger for the reversible VM — the core computation engine. - -**Features**: -- Stack visualisation (push/pop animated) -- Memory cells displayed as grid with highlighting on read/write -- Instruction pointer with assembly listing -- Step forward / step backward (reversible!) -- Breakpoints on instructions, memory addresses, stack depth -- Execution timeline scrubber — drag to any point in execution history -- Subroutine call graph (SubroutineRegistry visualisation) -- Port I/O monitoring (SEND/RECV buffers) -- Multi-VM view for multiplayer (each player's VM side by side) -- Instruction statistics: most-executed, cycle count, tier usage -- Export VM state snapshot (JSON) - -**Panel-L integration**: Display proof obligations for VM instruction correctness -**Panel-N integration**: ECHIDNA verifies instruction reversibility proofs -**Panel-W integration**: VM state feeds telemetry dashboard - -**Collaborative**: Child can step through VM execution while parent explains -the instruction semantics. "What happens if we SWAP here?" - ---- - -### Panel 4: Network Topology (SHOULD) - -**ID**: `PanelNetworkTopology` -**Kind**: viewer -**Icon**: `network` - -Visual map of the in-game network — devices, connections, zones, security levels. - -**Features**: -- Force-directed graph layout of network devices -- Colour-coded zones: LAN (green), VLAN (blue), External (red) -- Device icons matching in-game types (laptop, router, camera, firewall, PBX) -- Security level indicators (Open/Weak/Medium/Strong) -- Live packet flow animation (traceroute visualisation) -- Click device → open device GUI in Game Preview panel -- Defence flag badges on devices (tamperProof, decoy, canary, killSwitch, etc.) -- DNS resolution tree (Atlas 8.8.8.8, Nexus 1.1.1.1) -- SSH connection paths highlighted -- Drag-to-rearrange topology for level design -- Export topology as SVG/PNG - -**Panel-L integration**: Constraint editor for network rules (zone access, firewall rules) -**Panel-N integration**: Suggest network topology improvements, detect unreachable devices -**Panel-W integration**: Overlay on world canvas for spatial context - ---- - -### Panel 5: Level Architect (SHOULD) - -**ID**: `PanelLevelArchitect` -**Kind**: builder -**Icon**: `map` - -Visual level design tool — the PanLL version of IDApTIK-UMS. - -**Features**: -- Drag-and-drop device placement on level grid -- Guard patrol path editor (waypoint-based) -- Spawn point configuration -- Defence flag toggles per device (11 flags from LevelConfig.res) -- Alert threshold sliders -- Asset browser (from AssetPack manifest) -- Level validation: run VM simulation to check solvability -- Companion placement (Moletaire start position, food items) -- Level export to LevelConfig.res format -- Level import from existing configs -- Undo/redo with Valence checkpoint integration -- Side-by-side: edit left, preview right - -**Panel-L integration**: Formal constraints on level design (min exits, device connectivity) -**Panel-N integration**: AI difficulty estimation, auto-balance suggestions -**Panel-W integration**: Level metrics dashboard (estimated completion time, paths) - -**Collaborative**: Parent designs level structure, child places devices and tests. - ---- - -### Panel 6: Coprocessor Dashboard (SHOULD) - -**ID**: `PanelCoprocessors` -**Kind**: viewer -**Icon**: `chip` - -Monitor and inspect the 3 coprocessor backends (Compute, Security, I/O). - -**Features**: -- Real-time coprocessor call log -- Backend health status (Maths, Vector, Tensor, Physics, Crypto, Neural, Quantum, Audio, Graphics, I/O) -- Call frequency heatmap -- Performance metrics per backend -- Input/output inspection for individual calls -- CoprocessorManager dispatch log -- Backend toggle (enable/disable for testing) - -**Panel-L integration**: Coprocessor contracts (expected input ranges, output guarantees) -**Panel-N integration**: Anomaly detection on coprocessor usage patterns -**Panel-W integration**: Performance metrics feed world canvas - ---- - -### Panel 7: Multiplayer Monitor (COULD) - -**ID**: `PanelMultiplayer` -**Kind**: viewer -**Icon**: `users` - -Monitor the Elixir/Phoenix sync server and multiplayer state. - -**Features**: -- WebSocket connection status -- Phoenix channel subscriptions -- Player state diff (Hacker vs Observer roles) -- VMMessageBus traffic monitor -- Lamport clock visualisation (causal ordering) -- Device lock status (who's editing which device) -- Latency graph (client ↔ server round-trip) -- Sync server process tree (Horde distributed supervisor) -- ETS cache inspection -- Reconnection test trigger - -**Panel-L integration**: Protocol constraints from proven-servers gameserver spec -**Panel-N integration**: Predict desync risk from Lamport clock drift -**Panel-W integration**: Multiplayer health feeds world canvas - ---- - -### Panel 8: DLC Workshop (COULD) - -**ID**: `PanelDlcWorkshop` -**Kind**: builder -**Icon**: `puzzle` - -Create, test, and package DLC puzzle packs. - -**Features**: -- Puzzle editor with VM instruction composer -- Test runner for puzzle solutions (42-test suite integration) -- Difficulty classification -- Asset bundling for DLC distribution -- Import/export puzzle packs -- Puzzle chain editor (sequence of related puzzles) - -**Panel-L integration**: Puzzle solvability proofs (ECHIDNA checks reversibility) -**Panel-N integration**: AI-generated puzzle suggestions based on difficulty curve -**Panel-W integration**: Puzzle analytics (completion rates, hint usage) - ---- - -## Core eNSAID Features for IDApTIK - -### TyPELL (Type-Level Intelligence) - -TyPELL operates through Panel-L's constraint layer: - -| Feature | IDApTIK Application | -|---------|---------------------| -| **Type checking** | Validate LevelConfig.res against expected schema | -| **Exhaustiveness** | Ensure all DeviceType variants handled in DeviceFactory | -| **Constraint propagation** | If guard count > 5, alert threshold must be ≥ Medium | -| **Temporal types** | VM instruction sequences must be reversible (provable) | - -### ECHIDNA (Theorem Prover Integration) - -Panel-N's ECHIDNA advisor applied to game development: - -| Proof Obligation | What It Checks | -|------------------|----------------| -| VM reversibility | `undo(do(instruction, state)) == state` for all 23 instructions | -| Level solvability | At least one path from spawn to objective exists | -| Device reachability | All networked devices can reach gateway | -| Defence consistency | `tamperProof` and `decoy` are mutually exclusive | -| Save/load roundtrip | `deserialize(serialize(gameState)) == gameState` | -| Coprocessor safety | Input ranges produce valid outputs (no NaN, no overflow) | - -Trust Level applied: game builds only with Level 3+ proofs (multiple solver agreement). - -### NeSy (Neurosymbolic Reasoning) - -The binary star model applied to IDApTIK: - -- **Symbolic star** (Panel-L): VM instruction rules, network topology constraints, level design rules -- **Neural star** (Panel-N): AI-assisted level generation, difficulty estimation, playtest analysis -- **Barycentre** (Panel-W): Where symbolic proofs meet neural suggestions — the game preview with overlays - -### Agentic Features - -BoJ cartridge integration for autonomous development workflows: - -| Cartridge | IDApTIK Use | -|-----------|-------------| -| `database-mcp` | Save/load game state to VeriSimDB | -| `git-mcp` | Version control from within PanLL | -| `container-mcp` | Build and deploy game containers | -| `observe-mcp` | Game telemetry and performance monitoring | -| `nesy-mcp` | Neurosymbolic reasoning for level design | -| `agent-mcp` | Automated playtest workflows | -| `proof-mcp` | ECHIDNA proof submission from BoJ | - ---- - -## External Portfolio Integration - -### panic-attack (Existing Panel) - -Already wired. For IDApTIK: scan game code for unsafe patterns, command -injection in network simulation, ReScript-specific weak points. - -### Mass Panic (Existing Panel) - -Already wired. For IDApTIK: batch scan all monorepo subdirectories -(src/, vm/, shared/, dlc/, sync-server/). - -### VAB (Existing Panel) - -Already wired. For IDApTIK: compose the game's server stack from -proven-servers components (gameserver, websocket, dns, firewall protocols). - -### Databases (Existing Panel) - -Already wired. For IDApTIK: VeriSimDB for game telemetry persistence, -drift detection on game state, entity browser for level objects. - -### Capture (Existing Panel) - -Already wired. Critical for collaborative use — screenshot game state, -record development sessions, compare before/after level changes. - -### AI Panel (Existing) - -Already wired. For IDApTIK: Claude integration for code assistance, -level design suggestions, debugging help. This is the AI conversation -panel complementing the Valence Shell's Claude CLI. - ---- - -## Collaborative Features (Parent-Child) - -### Shared Session Mode - -- Both users see the same PanLL instance (same Tauri window or screen-shared) -- Valence Shell has "approval gate": child types command, parent approves -- Game Preview shows both players in multiplayer mode -- VM Inspector supports "explain mode": step-by-step with annotations - -### Recording and Sharing - -- **Session recording**: Valence Shell records terminal sessions (asciinema .cast) -- **Gameplay recording**: Game Preview records WebM clips -- **Screenshot**: Any panel → Capture panel → PNG export -- **Comparison views**: Capture panel's diff mode shows before/after changes -- **Share**: Export session bundles (terminal + gameplay + screenshots) as ZIP - -### Visualisation - -- **VM execution timeline**: Scrubber showing instruction flow with undo/redo -- **Network topology graph**: Force-directed device map with live traffic -- **Coprocessor heatmap**: Which backends are hot during gameplay -- **Level difficulty map**: Colour overlay showing hard/easy areas -- **Orbital drift aura**: Ambient visual showing symbolic/neural co-orbit health - ---- - -## Watcher Integration - -The existing watcher infrastructure feeds IDApTIK-specific events: - -| Watch Path | Panel Reaction | -|------------|----------------| -| `src/**/*.res` | Game Preview hot-reloads, panic-attack re-scans | -| `vm/lib/ocaml/**/*.res` | VM Inspector reloads instruction set, ECHIDNA re-verifies | -| `shared/src/**/*.res` | Coprocessor Dashboard refreshes backend status | -| `dlc/**/*.res` | DLC Workshop re-runs puzzle tests | -| `sync-server/**/*.ex` | Multiplayer Monitor checks sync server health | -| `raw-assets/**/*` | Game Preview triggers AssetPack rebuild | -| `src/app/screens/LevelConfig.res` | Level Architect reloads level definitions | - ---- - -## MuSCoCA Classification - -### MUST (Minimum Viable eNSAID) - -1. **Valence Shell panel** — embedded terminal with Claude Code, session recording, reversible ops -2. **Game Preview panel** — live iframe of Vite dev server with hot-reload -3. **VM Inspector panel** — visual debugger with step forward/backward -4. **Watcher integration** — file change events feed all IDApTIK panels -5. **Panel registration** — 8 new panel IDs in PanelSwitcherModel.res + PanelRegistry.res -6. **Model/Msg/Update wiring** — TEA integration for all MUST panels - -### SHOULD (Full Development Experience) - -7. **Network Topology panel** — force-directed graph of in-game network -8. **Level Architect panel** — visual level editor (PanLL version of UMS) -9. **Coprocessor Dashboard** — monitor compute/security/IO backends -10. **Shared session mode** — approval gate for child commands -11. **ECHIDNA proofs for VM** — reversibility verification in Panel-N -12. **BoJ cartridge integration** — database-mcp, git-mcp for dev workflows -13. **Gameplay recording** — WebM capture in Game Preview - -### COULD (Enhanced Experience) - -14. **Multiplayer Monitor** — Phoenix channel inspector -15. **DLC Workshop** — puzzle editor and test runner -16. **Level difficulty estimator** — AI-powered analysis in Panel-N -17. **Coprocessor anomaly detection** — NeSy reasoning on usage patterns -18. **VM execution timeline** — full scrubber with undo/redo visualisation -19. **Asset browser** — visual asset picker integrated with Level Architect -20. **Export session bundles** — ZIP of terminal + gameplay + screenshots - -### Corrective (Fix Existing Issues) - -21. **Watcher debounce tuning** — 500ms default may be too slow for game dev hot-reload -22. **Panel-N OODA cycle** — ensure agency phase tracking works with game-specific proofs -23. **Capture panel format** — add WebM and asciinema .cast alongside existing PNG -24. **Anti-Crash for game events** — validate game state transitions through circuit breaker - -### Adaptive (Respond to Change) - -25. **ReScript 13 migration panel** — when staging migration lands, track it in PanLL -26. **Multi-VM networking** — when VM Tier 5 lands, add cross-VM visualisation -27. **VeriSimDB temporal mode** — when per-level toggle ships, integrate with Level Architect -28. **Tauri 2 mobile** — adapt panels for tablet use (child on iPad, parent on desktop) - -### Perfective (Polish and Optimise) - -29. **Panel transitions** — smooth animations between IDApTIK panels -30. **Keyboard shortcuts** — game-dev-specific bindings (F5=run, F9=breakpoint, F10=step) -31. **Dark Start IDApTIK theme** — binary star animation with game characters -32. **Accessibility** — screen reader support for VM Inspector, colour-blind mode for topology -33. **Performance** — lazy-load IDApTIK panels only when IDApTIK repo is loaded -34. **Panel presets** — "IDApTIK Dev" workspace preset with recommended panel arrangement - ---- - -## Recommended Panel Arrangement: IDApTIK Dev Mode - -``` -┌─────────────────────────────────────────────────────────────┐ -│ Panel Bar (vertical, left) │ -│ ┌──────────┬──────────────────────┬───────────────────────┐ │ -│ │ Panel-L │ Panel-N │ Panel-W │ │ -│ │ Level │ ECHIDNA │ Game Preview │ │ -│ │ Rules │ VM Proofs │ (live iframe) │ │ -│ │ │ │ │ │ -│ │ Device │ AI Commentary │ ┌─────────────┐ │ │ -│ │ Flags │ │ │ Network │ │ │ -│ │ │ Trust Level: │ │ Topology │ │ │ -│ │ Network │ ████ L3 │ │ Overlay │ │ │ -│ │ Constr. │ │ └─────────────┘ │ │ -│ ├──────────┴──────────────────────┴───────────────────────┤ │ -│ │ Valence Shell (bottom dock) │ │ -│ │ $ deno task dev │ │ -│ │ $ claude "help me add a new device type" │ │ -│ │ [Recording ●] [Share] [Screenshot] [Approval Gate: ON] │ │ -│ └─────────────────────────────────────────────────────────┘ │ -│ Status Bar: IDApTIK v0.1.0 | ReScript 12.1.0 | 0 errors │ -└─────────────────────────────────────────────────────────────┘ -``` - ---- - -## Implementation Order - -### Phase 1: Shell First (Week 1-2) - -1. Add `PanelValenceShell` to PanelSwitcherModel.res -2. Create ValenceShellModel.res, ValenceShellMsg.res -3. Wire PTY via `@tauri-apps/plugin-shell` -4. Basic terminal emulator (xterm.js via Tauri webview) -5. Claude Code launch command -6. Session recording (asciinema format) - -### Phase 2: Game Preview (Week 2-3) - -1. Add `PanelGamePreview` to registry -2. Embed Vite dev server output in iframe/webview -3. Hot-reload integration with watcher -4. FPS overlay and render stats -5. Screenshot to Capture panel - -### Phase 3: VM Inspector (Week 3-4) - -1. Add `PanelVmInspector` to registry -2. Connect to VM state via Tauri command bridge -3. Stack and memory visualisation -4. Step forward/backward controls -5. Execution timeline scrubber - -### Phase 4: Network + Level Tools (Week 5-6) - -1. Network Topology panel (force-directed graph) -2. Level Architect panel (device placement) -3. Connect both to LevelConfig.res - -### Phase 5: Collaborative Features (Week 7-8) - -1. Shared session mode -2. Approval gate for Valence Shell -3. Recording and sharing infrastructure -4. Workspace preset for "IDApTIK Dev Mode" - ---- - -## Technical Notes - -### Panel Registration Pattern - -Each new panel requires: -1. `PanelSwitcherModel.res` — add variant to `panelId` -2. `PanelRegistry.res` — add `panelMeta` entry -3. `src/model/XxxModel.res` — domain types -4. `src/components/Xxx.res` — view function -5. `Model.res` — `include XxxModel` -6. `Msg.res` — add message type + variants -7. `Update.res` — add pattern match cases -8. `View.res` — add to `renderActivePanel` dispatch - -### Terminal Emulator Options - -- **xterm.js** — industry standard, WebGL renderer, accessible -- Loaded via Tauri webview, communicates with Valence shell binary via PTY -- Alternative: raw ANSI rendering in Tea_Html (simpler but less capable) - -### Game Preview Embedding - -- Tauri supports multiple webviews — one for PanLL, one for game preview -- Communication via Tauri event bus (not postMessage) -- Game preview webview loads `http://localhost:8080` (Vite dev server) - -### VM State Bridge - -- VM runs in game's Vite webview -- Expose VM state via global `window.__IDAPTIK_VM_STATE__` -- PanLL reads via Tauri inter-webview messaging -- Or: VM state serialised to file, watcher picks it up (simpler, decoupled) - ---- - -## Simulation, Emulation, and Beyond - -### Simulation Mode - -Run the game logic without rendering — useful for: -- Automated playtesting (agent-mcp runs through levels) -- Performance profiling (how fast can the VM execute 10k instructions?) -- Puzzle solvability checking (brute-force all SWAP/ADD sequences) - -### Emulation Mode - -Run the VM in a sandboxed PanLL panel without the full game: -- Test individual instructions -- Compose subroutines -- Verify reversibility interactively -- Educational: "Here's how XOR works" with animated visualisation - -### Preview Mode - -Live game preview with overlays — the standard development view. - -### Watch Mode - -Passive monitoring — watcher feeds events, panels update, no interaction required. -Good for "leave it running while we code" workflows. - ---- - -## Summary - -PanLL becomes the **mission control for IDApTIK development** by adding 8 -game-specific panels to the existing 22-panel suite. The Valence Shell is the -foundation — it gives parent and child a shared, recorded, reversible terminal -with Claude Code integration. The Game Preview, VM Inspector, and Network -Topology panels provide the visual development experience. ECHIDNA proves VM -correctness, BoJ cartridges automate workflows, and panic-attack keeps the -codebase secure. - -The MuSCoCA classification ensures we build the most valuable panels first -(Shell, Preview, VM Inspector) while planning for collaborative features, -multiplayer monitoring, and DLC creation tools. diff --git a/docs/design/DESIGN-2026-03-14-phase3-constraint-core.adoc b/docs/design/DESIGN-2026-03-14-phase3-constraint-core.adoc new file mode 100644 index 00000000..ac9039d8 --- /dev/null +++ b/docs/design/DESIGN-2026-03-14-phase3-constraint-core.adoc @@ -0,0 +1,310 @@ +== Revised Five-Phase Architecture Note + +*PanLL / eNSAID / Phase-3 Constraint-Core Reframing* *Date*: 2026-03-14 +*Author*: Jonathan D.A. Jewell j.d.a.jewell@open.ac.uk *Status*: +Accepted + +=== Executive view + +The original five phases still make sense, but Phase 3 is no longer just +one stage among peers. It becomes the semantic core of the system. + +That means the surrounding phases should be reinterpreted like this: + +* Phase 1 builds the substrate the constraint engine needs +* Phase 2 captures satisfiable intent before code appears +* Phase 3 propagates, checks, and repairs obligations +* Phase 4 turns unsatisfied obligations into policy and gating +* Phase 5 makes the live constraint state legible to humans + +So the architecture is still five phases, but it is now much more of a +hub-and-spoke model centered on Phase 3. + +=== Impact summary + +[width="100%",cols="17%,20%,20%,16%,27%",options="header",] +|=== +|Phase |Old role |New role |Impact |Change now? +|1 |infrastructure |semantic substrate |moderate/substantial |yes + +|2 |creation-time checks |intent capture + satisfiability |moderate |yes + +|3 |wiring checks |constraint propagation engine |major |yes + +|4 |prevent half-baked panels |policy/gating over constraint state +|small/moderate |later, lightly + +|5 |audit visibility |operator-facing constraint observability |moderate +|later, after 3 stabilises +|=== + +=== Phase-by-phase restatement + +==== Phase 1 — Constraint Substrate + +*Old meaning:* Pure infrastructure. Invisible, but everything depends on +it. + +*New meaning:* Build the language and machinery that make the later +phases meaningful. + +This phase now owns: + +* contract vocabulary +* internal representation of panel obligations +* panel graph extraction hooks +* constraint kinds +* propagation machinery +* diagnostics model +* patch planning primitives + +*Why it changes:* If Phase 3 becomes a compiler-like constraint engine, +then Phase 1 cannot remain generic plumbing. It has to provide the +semantic substrate for constraint evaluation. + +*What must change now:* + +* define the smallest viable contract vocabulary +* define invariant categories +* define dependency relationships between obligations +* define machine-readable diagnostic codes +* define repairability classes + +*What can wait:* + +* fancy DSL syntax +* advanced fixpoint machinery +* proof-style formalism +* rich visual graph tooling + +*Judgment:* This is one of the two most important phases to revisit +immediately. + +==== Phase 2 — Intent Capture and Satisfiability + +*Old meaning:* Catch problems at creation time, the cheapest point to +fix. + +*New meaning:* Ensure that the thing being requested is coherent and +satisfiable before generation or wiring begins. + +This phase should now validate: + +* incomplete contracts +* contradictory options +* missing required declarations +* impossible combinations +* under-specified panel definitions + +*Why it changes:* Once constraints are first-class, creation-time +checking stops being a bag of ad hoc heuristics and becomes front-loaded +contract validation. + +*What must change now:* + +* shift from file-template validation to contract validation +* require explicit declaration of key obligations +* reject incoherent requests early +* emit Phase-3-compatible obligation records rather than bespoke +warnings + +*What can wait:* + +* conversational authoring assistant niceties +* advanced "`did you mean?`" repair suggestions +* interactive constraint editing UI + +*Judgment:* Needs meaningful reframing now, but not a radical rewrite. + +==== Phase 3 — Constraint Propagation and Wiring Realization + +*Old meaning:* Catch wiring failures after files exist. + +*New meaning:* Act as the constraint core of the entire system. + +This phase should: + +* ingest contract declarations +* infer repo facts +* propagate obligations +* identify bottlenecks +* distinguish root failures from downstream noise +* classify failures as repairable or non-repairable +* optionally synthesize safe repairs + +*Why it changes:* This is where the "`Theory of Constraints as +first-class`" idea lands properly. + +Instead of merely reporting: + +* missing route +* missing message +* missing test + +it can report: + +* primary bottleneck +* blocked downstream obligations +* constraint dependency chain +* minimum repair set + +That is much more powerful than linting. + +*What must change now:* + +* redesign this phase around obligations, dependencies, and propagation +* define root-vs-derived failures +* define safe repair classes +* make it the single producer of canonical build/audit truth + +*What can wait:* + +* richer bespoke language +* advanced planner/repair synthesis +* formal solver backends +* multi-panel global optimisation + +*Judgment:* This is the real redesign. It is the heart of the shift. + +==== Phase 4 — Completion Policy and Gating + +*Old meaning:* Prevent half-baked panels. + +*New meaning:* Translate constraint status into policy decisions. + +Examples: + +* do not register panel as live unless required obligations are +satisfied +* do not merge unless minimum viability obligations are green +* allow experimental/draft mode under explicit exemption rules +* differentiate "`exists,`" "`wired,`" "`viable,`" and "`ship-ready`" + +*Why it changes:* A strong Phase 3 makes Phase 4 simpler. Phase 4 should +not independently rediscover logic that Phase 3 already knows. + +*What must change now:* Mostly wording and design intent: + +* define gating thresholds +* define states like draft / experimental / viable / releasable +* define exemption and override semantics + +*What can wait:* + +* deep implementation work +* complex policy dashboards +* multi-role approval workflows + +*Judgment:* This phase changes less than it first appears. It becomes a +policy consumer, not a logic engine. + +==== Phase 5 — Audit and Operator Trust + +*Old meaning:* Show the human audit results so they trust the bot. + +*New meaning:* Expose the live state of the constraint system in +human-usable form. + +Instead of a flat pass/fail list, Phase 5 should show: + +* active bottleneck +* unsatisfied obligations +* dependency chain +* repair suggestions +* repairability status +* confidence / health / completeness state +* what changed since last run + +*Why it changes:* If Phase 3 becomes richer, Phase 5 gets richer too — +but mostly as a presentation layer. + +*What must change now:* Only enough to ensure the data model is +anticipated: + +* define what operators need to see +* define the trust states +* define the minimum useful report shape + +*What can wait:* + +* polished visual dashboard +* timeline/history views +* comparative runs +* embedded "`operator cockpit`" UI + +*Judgment:* Needs reframing, but implementation can mostly wait until +the Phase 3 data model settles. + +=== Recommended new wording for the five phases + +==== Phase 1 — Constraint Substrate + +Build the internal language, graph model, and diagnostic vocabulary that +make constraint-aware panel realization possible. + +==== Phase 2 — Intent Capture and Satisfiability + +Catch incoherent, incomplete, or contradictory panel contracts before +generation and wiring begin. + +==== Phase 3 — Constraint Propagation and Wiring Realization + +Evaluate panel obligations against repo reality, identify bottlenecks +and missing joins, and generate safe repairs where possible. + +==== Phase 4 — Completion Policy and Gating + +Use constraint satisfaction status to block half-realized panels and +define the thresholds for draft, viable, and releasable states. + +==== Phase 5 — Audit and Operator Trust + +Make constraint state, bottlenecks, and repair outcomes visible enough +that a human operator can trust the system. + +=== What should change first + +==== Change now + +[arabic] +. *Reword all five phases* — even before implementation. This aligns the +mental model. +. *Redesign Phase 3 as the semantic core* — this is the big move. +. *Tighten Phase 1 around substrate, not generic plumbing* — without +this, Phase 3 will sprawl or become ad hoc. +. *Reframe Phase 2 around satisfiability* — prevents garbage from +reaching the constraint engine. + +==== Change later + +[arabic, start=5] +. *Rebuild Phase 4 around policy thresholds* — likely smaller than +feared. +. *Rebuild Phase 5 around bottleneck visibility and trust* — important, +but downstream of the core model. + +=== Practical risk assessment + +* *Small risk:* Phase 4 and 5 become slightly misaligned if left +untouched for a while. +* *Medium risk:* Phase 2 remains too template-centric and feeds weak +intent into the new engine. +* *Biggest risk:* Phase 3 becomes clever but underspecified because +Phase 1 did not provide a strong enough vocabulary. + +That last one is the main trap. + +=== Strongest recommendation + +Treat this as a controlled re-centering, not a wholesale rewrite. + +That means: + +* do not scrap the five-phase model +* do not redesign every phase equally +* do promote Phase 3 into the core +* do retool Phase 1 and 2 first +* do let Phase 4 and 5 become thinner consumers + +*In one sentence:* You need moderate architectural changes around the +edges, but only one true redesign in the middle. diff --git a/docs/design/DESIGN-2026-03-14-phase3-constraint-core.md b/docs/design/DESIGN-2026-03-14-phase3-constraint-core.md deleted file mode 100644 index 848eee95..00000000 --- a/docs/design/DESIGN-2026-03-14-phase3-constraint-core.md +++ /dev/null @@ -1,269 +0,0 @@ - - -# Revised Five-Phase Architecture Note - -**PanLL / eNSAID / Phase-3 Constraint-Core Reframing** -**Date**: 2026-03-14 -**Author**: Jonathan D.A. Jewell -**Status**: Accepted - -## Executive view - -The original five phases still make sense, but Phase 3 is no longer just one stage among peers. It becomes the semantic core of the system. - -That means the surrounding phases should be reinterpreted like this: - -- Phase 1 builds the substrate the constraint engine needs -- Phase 2 captures satisfiable intent before code appears -- Phase 3 propagates, checks, and repairs obligations -- Phase 4 turns unsatisfied obligations into policy and gating -- Phase 5 makes the live constraint state legible to humans - -So the architecture is still five phases, but it is now much more of a hub-and-spoke model centered on Phase 3. - -## Impact summary - -| Phase | Old role | New role | Impact | Change now? | -|-------|----------|----------|--------|-------------| -| 1 | infrastructure | semantic substrate | moderate/substantial | yes | -| 2 | creation-time checks | intent capture + satisfiability | moderate | yes | -| 3 | wiring checks | constraint propagation engine | major | yes | -| 4 | prevent half-baked panels | policy/gating over constraint state | small/moderate | later, lightly | -| 5 | audit visibility | operator-facing constraint observability | moderate | later, after 3 stabilises | - -## Phase-by-phase restatement - -### Phase 1 — Constraint Substrate - -**Old meaning:** Pure infrastructure. Invisible, but everything depends on it. - -**New meaning:** Build the language and machinery that make the later phases meaningful. - -This phase now owns: - -- contract vocabulary -- internal representation of panel obligations -- panel graph extraction hooks -- constraint kinds -- propagation machinery -- diagnostics model -- patch planning primitives - -**Why it changes:** If Phase 3 becomes a compiler-like constraint engine, then Phase 1 cannot remain generic plumbing. It has to provide the semantic substrate for constraint evaluation. - -**What must change now:** - -- define the smallest viable contract vocabulary -- define invariant categories -- define dependency relationships between obligations -- define machine-readable diagnostic codes -- define repairability classes - -**What can wait:** - -- fancy DSL syntax -- advanced fixpoint machinery -- proof-style formalism -- rich visual graph tooling - -**Judgment:** This is one of the two most important phases to revisit immediately. - -### Phase 2 — Intent Capture and Satisfiability - -**Old meaning:** Catch problems at creation time, the cheapest point to fix. - -**New meaning:** Ensure that the thing being requested is coherent and satisfiable before generation or wiring begins. - -This phase should now validate: - -- incomplete contracts -- contradictory options -- missing required declarations -- impossible combinations -- under-specified panel definitions - -**Why it changes:** Once constraints are first-class, creation-time checking stops being a bag of ad hoc heuristics and becomes front-loaded contract validation. - -**What must change now:** - -- shift from file-template validation to contract validation -- require explicit declaration of key obligations -- reject incoherent requests early -- emit Phase-3-compatible obligation records rather than bespoke warnings - -**What can wait:** - -- conversational authoring assistant niceties -- advanced "did you mean?" repair suggestions -- interactive constraint editing UI - -**Judgment:** Needs meaningful reframing now, but not a radical rewrite. - -### Phase 3 — Constraint Propagation and Wiring Realization - -**Old meaning:** Catch wiring failures after files exist. - -**New meaning:** Act as the constraint core of the entire system. - -This phase should: - -- ingest contract declarations -- infer repo facts -- propagate obligations -- identify bottlenecks -- distinguish root failures from downstream noise -- classify failures as repairable or non-repairable -- optionally synthesize safe repairs - -**Why it changes:** This is where the "Theory of Constraints as first-class" idea lands properly. - -Instead of merely reporting: - -- missing route -- missing message -- missing test - -it can report: - -- primary bottleneck -- blocked downstream obligations -- constraint dependency chain -- minimum repair set - -That is much more powerful than linting. - -**What must change now:** - -- redesign this phase around obligations, dependencies, and propagation -- define root-vs-derived failures -- define safe repair classes -- make it the single producer of canonical build/audit truth - -**What can wait:** - -- richer bespoke language -- advanced planner/repair synthesis -- formal solver backends -- multi-panel global optimisation - -**Judgment:** This is the real redesign. It is the heart of the shift. - -### Phase 4 — Completion Policy and Gating - -**Old meaning:** Prevent half-baked panels. - -**New meaning:** Translate constraint status into policy decisions. - -Examples: - -- do not register panel as live unless required obligations are satisfied -- do not merge unless minimum viability obligations are green -- allow experimental/draft mode under explicit exemption rules -- differentiate "exists," "wired," "viable," and "ship-ready" - -**Why it changes:** A strong Phase 3 makes Phase 4 simpler. Phase 4 should not independently rediscover logic that Phase 3 already knows. - -**What must change now:** Mostly wording and design intent: - -- define gating thresholds -- define states like draft / experimental / viable / releasable -- define exemption and override semantics - -**What can wait:** - -- deep implementation work -- complex policy dashboards -- multi-role approval workflows - -**Judgment:** This phase changes less than it first appears. It becomes a policy consumer, not a logic engine. - -### Phase 5 — Audit and Operator Trust - -**Old meaning:** Show the human audit results so they trust the bot. - -**New meaning:** Expose the live state of the constraint system in human-usable form. - -Instead of a flat pass/fail list, Phase 5 should show: - -- active bottleneck -- unsatisfied obligations -- dependency chain -- repair suggestions -- repairability status -- confidence / health / completeness state -- what changed since last run - -**Why it changes:** If Phase 3 becomes richer, Phase 5 gets richer too — but mostly as a presentation layer. - -**What must change now:** Only enough to ensure the data model is anticipated: - -- define what operators need to see -- define the trust states -- define the minimum useful report shape - -**What can wait:** - -- polished visual dashboard -- timeline/history views -- comparative runs -- embedded "operator cockpit" UI - -**Judgment:** Needs reframing, but implementation can mostly wait until the Phase 3 data model settles. - -## Recommended new wording for the five phases - -### Phase 1 — Constraint Substrate - -Build the internal language, graph model, and diagnostic vocabulary that make constraint-aware panel realization possible. - -### Phase 2 — Intent Capture and Satisfiability - -Catch incoherent, incomplete, or contradictory panel contracts before generation and wiring begin. - -### Phase 3 — Constraint Propagation and Wiring Realization - -Evaluate panel obligations against repo reality, identify bottlenecks and missing joins, and generate safe repairs where possible. - -### Phase 4 — Completion Policy and Gating - -Use constraint satisfaction status to block half-realized panels and define the thresholds for draft, viable, and releasable states. - -### Phase 5 — Audit and Operator Trust - -Make constraint state, bottlenecks, and repair outcomes visible enough that a human operator can trust the system. - -## What should change first - -### Change now - -1. **Reword all five phases** — even before implementation. This aligns the mental model. -2. **Redesign Phase 3 as the semantic core** — this is the big move. -3. **Tighten Phase 1 around substrate, not generic plumbing** — without this, Phase 3 will sprawl or become ad hoc. -4. **Reframe Phase 2 around satisfiability** — prevents garbage from reaching the constraint engine. - -### Change later - -5. **Rebuild Phase 4 around policy thresholds** — likely smaller than feared. -6. **Rebuild Phase 5 around bottleneck visibility and trust** — important, but downstream of the core model. - -## Practical risk assessment - -- **Small risk:** Phase 4 and 5 become slightly misaligned if left untouched for a while. -- **Medium risk:** Phase 2 remains too template-centric and feeds weak intent into the new engine. -- **Biggest risk:** Phase 3 becomes clever but underspecified because Phase 1 did not provide a strong enough vocabulary. - -That last one is the main trap. - -## Strongest recommendation - -Treat this as a controlled re-centering, not a wholesale rewrite. - -That means: - -- do not scrap the five-phase model -- do not redesign every phase equally -- do promote Phase 3 into the core -- do retool Phase 1 and 2 first -- do let Phase 4 and 5 become thinner consumers - -**In one sentence:** You need moderate architectural changes around the edges, but only one true redesign in the middle. diff --git a/docs/design/DESIGN-2026-03-16-feedback-o-tron-evolution.adoc b/docs/design/DESIGN-2026-03-16-feedback-o-tron-evolution.adoc new file mode 100644 index 00000000..5961ff71 --- /dev/null +++ b/docs/design/DESIGN-2026-03-16-feedback-o-tron-evolution.adoc @@ -0,0 +1,328 @@ +== Feedback-o-Tron Evolution — Self-Improving Feedback Governance + +=== Motivation + +During a security incident report to Anthropic (issue #34819), the +Feedback-o-Tron successfully structured and filed the report, but three +gaps emerged: + +[arabic] +. *No pre-flight duplicate check* — we filed without checking if similar +issues existed, triggering a bot that threatened auto-closure +. *No automated bot-response handling* — a programmatic bot replied with +"`possible duplicates`" and we had to manually triage and respond +. *No feedback-on-feedback loop* — the Feedback-o-Tron gathers feedback +about other systems but doesn’t solicit or process feedback about itself + +This design addresses all three, plus adds a dual-mode feedback +collection system (human questionnaire + LLM/SLM deep-dive). + +''''' + +=== 1. Pre-Flight Duplicate Detection + +==== What It Does + +Before submitting any issue/report/PR to an external tracker, the +Feedback-o-Tron searches for existing related items and presents them to +the operator for review. + +==== Implementation + +.... +FeedbackOTron.preflight(target, report) -> + 1. Search target repo for similar issues (title keywords + body similarity) + 2. Search closed issues too (may have been fixed) + 3. Score each match: exact_title (0.9), keyword_overlap (0.5-0.8), + body_similarity via TF-IDF (0.3-0.7) + 4. Present matches above 0.4 threshold to operator + 5. Operator decides: "new issue", "comment on existing", or "abort" + 6. If "comment on existing": auto-draft a comment linking the new evidence +.... + +==== PanLL Integration + +* Panel-L: constraint "`no duplicate submissions without review`" +* Panel-N: similarity scoring via TF-IDF or embedding cosine +* Panel-W: side-by-side comparison of our report vs existing issues + +==== Files to Create/Modify + +* `+lib/feedback_o_tron/preflight.ex+` — duplicate detection module +* `+lib/feedback_o_tron/similarity.ex+` — TF-IDF text similarity scoring +* Extend `+FeedbackOTron.submit/3+` to call preflight before dispatch + +''''' + +=== 2. Automated Bot Response Handler + +==== What It Does + +When a programmatic bot (not a human) responds to our filed issues, the +Feedback-o-Tron automatically triages and responds: + +* *Duplicate bot*: fetch the suggested duplicates, compare them against +our report, draft a differentiation response or acknowledge duplication +* *Stale bot*: respond with "`still relevant`" + evidence +* *Label bot*: acknowledge or contest incorrect labels +* *Close bot*: contest with justification or accept gracefully + +==== Bot Detection + +.... +is_bot?(comment) -> + author ends with "[bot]" OR + author in known_bots (github-actions, stale, dependabot) OR + body contains "Generated with" / "This is an automated" OR + body matches structured template (numbered list of links) +.... + +==== Response Strategy + +.... +handle_bot_response(issue, comment) -> + case detect_bot_intent(comment): + :duplicate_warning -> + for each suggested_duplicate: + fetch_issue(duplicate) + score = compare_issues(our_issue, duplicate) + if score > 0.85: accept_duplicate(issue, duplicate) + else: draft_differentiation(issue, duplicate, differences) + post_response(issue, drafted_response) + if all_accepted: close_our_issue("Duplicate of #NNN") + else: thumbs_down(comment) to prevent auto-close + + :stale_warning -> + post_response(issue, "Still relevant: [evidence]") + + :label_change -> + if label_incorrect: contest("This is X not Y because...") + else: acknowledge silently + + :auto_close -> + if closure_justified: accept + else: reopen with justification +.... + +==== Safety Triangle Integration + +* *Eliminate* (>0.95): bot says "`duplicate`" and our comparison agrees +→ auto-close with "`confirmed duplicate of #NNN, thank you`" +* *Substitute* (>0.85): bot says "`duplicate`" but partial match → +auto-draft differentiation, human reviews before posting +* *Control* (<0.85): bot says something unexpected → flag for human + +==== Files to Create + +* `+lib/feedback_o_tron/bot_handler.ex+` — bot detection and response +* `+lib/feedback_o_tron/issue_comparator.ex+` — deep issue comparison +* `+lib/feedback_o_tron/auto_responder.ex+` — draft and post responses + +''''' + +=== 3. Feedback-on-Feedback Loop (Self-Improvement) + +==== What It Does + +The Feedback-o-Tron solicits feedback about itself, processes it through +Hypatia’s neural networks, and evolves its own behaviour. + +==== Architecture + +.... + ┌──────────────────────┐ + │ External Users │ + │ (GitHub, PanLL) │ + └──────────┬───────────┘ + │ feedback + ┌──────────▼───────────┐ + │ Feedback-o-Tron │ + │ (collects, routes) │ + └──────────┬───────────┘ + │ self-feedback + ┌──────────▼───────────┐ + │ Hypatia │ + │ (learns, adapts) │ + │ ESN + RBF networks │ + └──────────┬───────────┘ + │ updated patterns + ┌──────────▼───────────┐ + │ Feedback-o-Tron │ + │ (evolved rules) │ + └──────────────────────┘ +.... + +==== Self-Feedback Collection + +After every feedback submission, the Feedback-o-Tron asks: - Was the +report filed to the right place? - Was the severity assessment accurate? +- Did the pre-flight catch relevant duplicates? - Did the bot handler +respond appropriately? - Was the outcome satisfactory? + +These answers feed into Hypatia’s training pipeline as outcome data, +adjusting the ESN confidence scores for future submissions. + +==== Hypatia Correspondence Protocol + +.... +FeedbackOTron -> Hypatia: + - Submit outcome records (success/failure/partial) + - Request pattern analysis ("what types of reports get closed?") + - Receive updated confidence thresholds + +Hypatia -> FeedbackOTron: + - Updated Safety Triangle thresholds per target repo + - Pattern alerts ("issues mentioning X get auto-closed on repo Y") + - Severity calibration adjustments +.... + +==== Files to Create + +* `+lib/feedback_o_tron/self_feedback.ex+` — self-assessment after +submissions +* `+lib/feedback_o_tron/hypatia_bridge.ex+` — bidirectional Hypatia +comms +* Extend Hypatia’s `+training_pipeline.ex+` with feedback-o-tron outcome +data + +''''' + +=== 4. Dual-Mode Feedback Collection Forms + +==== The Problem + +Humans give brief, high-signal feedback ("`this is broken`", "`love +this`"). LLMs/SLMs can give detailed, structured feedback but need +prompting. Currently we only support unstructured text input. + +==== Solution: Two Feedback Modes + +===== Mode A: Human Questionnaire (Quick) + +5 questions, ~30 seconds: + +.... +1. What did you use? [dropdown: panel name / tool name / workflow] +2. Did it work? [Yes / Partially / No] +3. How frustrated were you? [1-5 slider → feeds Vexometer] +4. What would you improve? [free text, optional] +5. Would you recommend this? [Yes / Maybe / No → NPS-style] +.... + +Rendered as a clean form in PanLL’s Feedback-o-Tron panel. Results +stored as structured JSON in VeriSimDB. + +===== Mode B: LLM/SLM Deep-Dive Questionnaire + +If the user opts in ("`Let my AI assistant provide detailed feedback`"), +the Feedback-o-Tron sends a structured prompt to the user’s local LLM or +cloud provider: + +.... +Prompt: "You have been using [TOOL] version [VERSION] for [DURATION]. +Based on your session, please provide detailed feedback on: + +1. FUNCTIONALITY: Did all features work as documented? List any that + didn't, with reproduction steps. + +2. ERGONOMICS: Rate the cognitive load (1-10). Were error messages + helpful? Was the workflow intuitive? Identify friction points. + +3. PERFORMANCE: Note any latency, hangs, or resource issues. + Include approximate timing if possible. + +4. DOCUMENTATION: Was the documentation sufficient? What was missing? + +5. INTEGRATION: How well did this tool work with other tools in your + workflow? Any compatibility issues? + +6. SUGGESTIONS: Prioritised list of improvements, each with: + - Description + - Severity (critical/high/medium/low) + - Estimated user impact + +7. COMPARISON: If you've used similar tools, how does this compare? + What does it do better/worse? + +Format as JSON for machine processing." +.... + +==== Why This Matters + +* Human feedback is high-signal but low-volume (people don’t fill forms) +* LLM feedback is lower-signal but high-volume and highly structured +* Combined: humans flag what matters, LLMs fill in the details +* The Feedback-o-Tron can collect 10x more feedback by offering the LLM +option alongside the human one +* SLMs (local models) can provide feedback without API costs + +==== Privacy + +* LLM feedback mode is opt-in only +* No session data sent without explicit consent +* Local SLM option means feedback never leaves the user’s machine +* All feedback is attributed (human vs LLM) so analysis can weight +accordingly + +==== Files to Create + +* `+src/components/FeedbackForm.res+` — dual-mode form component +* `+src/model/FeedbackFormModel.res+` — form state types +* `+src/core/FeedbackFormEngine.res+` — form logic + LLM prompt builder +* `+src/commands/FeedbackFormCmd.res+` — submission to VeriSimDB + +''''' + +=== 5. Feedback-o-Tron Self-Invitation + +==== What It Does + +The Feedback-o-Tron proactively invites feedback at natural moments: + +* After completing a multi-step workflow +* After filing an issue/PR (was the process smooth?) +* After a tool error or crash recovery +* Periodically (weekly digest prompt) +* After significant version updates + +==== Implementation + +Non-intrusive toast notification in PanLL’s status bar: "`How was that? +[Quick feedback] [Detailed feedback] [Not now]`" + +Frequency capped: max 1 invitation per session, max 3 per week. "`Not +now`" suppresses for 48 hours. + +==== Integration with Cognitive Governance + +The Vexometer monitors whether feedback invitations themselves cause +friction. If users consistently dismiss them → reduce frequency. If +users engage → maintain or slightly increase. + +''''' + +=== Implementation Priority + +[arabic] +. *Pre-flight duplicate detection* — prevents the exact problem that +triggered this design (highest immediate value) +. *Bot response handler* — automates the tedious triage work +. *Human feedback form* — basic structured collection +. *LLM/SLM feedback mode* — force multiplier for feedback volume +. *Self-feedback loop* — long-term self-improvement +. *Hypatia bridge* — closes the learning loop + +=== Dependencies + +* Hypatia ESN/RBF training pipeline (exists, 376 tests passing) +* VeriSimDB for feedback storage (exists, connected) +* PanLL TEA framework for form components (exists) +* BoJ cartridge for external API calls (exists) + +''''' + +_This design was prompted by GitHub issue anthropics/claude-code#34819, +where the Feedback-o-Tron filed a security report but didn’t pre-check +for duplicates, and the subsequent bot interaction had to be handled +manually. Every gap identified here was a real pain point from a single +session._ diff --git a/docs/design/DESIGN-2026-03-16-feedback-o-tron-evolution.md b/docs/design/DESIGN-2026-03-16-feedback-o-tron-evolution.md deleted file mode 100644 index d15c9b82..00000000 --- a/docs/design/DESIGN-2026-03-16-feedback-o-tron-evolution.md +++ /dev/null @@ -1,331 +0,0 @@ - - - - - - -# Feedback-o-Tron Evolution — Self-Improving Feedback Governance - -## Motivation - -During a security incident report to Anthropic (issue #34819), the -Feedback-o-Tron successfully structured and filed the report, but three -gaps emerged: - -1. **No pre-flight duplicate check** — we filed without checking if similar - issues existed, triggering a bot that threatened auto-closure -2. **No automated bot-response handling** — a programmatic bot replied with - "possible duplicates" and we had to manually triage and respond -3. **No feedback-on-feedback loop** — the Feedback-o-Tron gathers feedback - about other systems but doesn't solicit or process feedback about itself - -This design addresses all three, plus adds a dual-mode feedback collection -system (human questionnaire + LLM/SLM deep-dive). - ---- - -## 1. Pre-Flight Duplicate Detection - -### What It Does - -Before submitting any issue/report/PR to an external tracker, the -Feedback-o-Tron searches for existing related items and presents them -to the operator for review. - -### Implementation - -``` -FeedbackOTron.preflight(target, report) -> - 1. Search target repo for similar issues (title keywords + body similarity) - 2. Search closed issues too (may have been fixed) - 3. Score each match: exact_title (0.9), keyword_overlap (0.5-0.8), - body_similarity via TF-IDF (0.3-0.7) - 4. Present matches above 0.4 threshold to operator - 5. Operator decides: "new issue", "comment on existing", or "abort" - 6. If "comment on existing": auto-draft a comment linking the new evidence -``` - -### PanLL Integration - -- Panel-L: constraint "no duplicate submissions without review" -- Panel-N: similarity scoring via TF-IDF or embedding cosine -- Panel-W: side-by-side comparison of our report vs existing issues - -### Files to Create/Modify - -- `lib/feedback_o_tron/preflight.ex` — duplicate detection module -- `lib/feedback_o_tron/similarity.ex` — TF-IDF text similarity scoring -- Extend `FeedbackOTron.submit/3` to call preflight before dispatch - ---- - -## 2. Automated Bot Response Handler - -### What It Does - -When a programmatic bot (not a human) responds to our filed issues, -the Feedback-o-Tron automatically triages and responds: - -- **Duplicate bot**: fetch the suggested duplicates, compare them against - our report, draft a differentiation response or acknowledge duplication -- **Stale bot**: respond with "still relevant" + evidence -- **Label bot**: acknowledge or contest incorrect labels -- **Close bot**: contest with justification or accept gracefully - -### Bot Detection - -``` -is_bot?(comment) -> - author ends with "[bot]" OR - author in known_bots (github-actions, stale, dependabot) OR - body contains "Generated with" / "This is an automated" OR - body matches structured template (numbered list of links) -``` - -### Response Strategy - -``` -handle_bot_response(issue, comment) -> - case detect_bot_intent(comment): - :duplicate_warning -> - for each suggested_duplicate: - fetch_issue(duplicate) - score = compare_issues(our_issue, duplicate) - if score > 0.85: accept_duplicate(issue, duplicate) - else: draft_differentiation(issue, duplicate, differences) - post_response(issue, drafted_response) - if all_accepted: close_our_issue("Duplicate of #NNN") - else: thumbs_down(comment) to prevent auto-close - - :stale_warning -> - post_response(issue, "Still relevant: [evidence]") - - :label_change -> - if label_incorrect: contest("This is X not Y because...") - else: acknowledge silently - - :auto_close -> - if closure_justified: accept - else: reopen with justification -``` - -### Safety Triangle Integration - -- **Eliminate** (>0.95): bot says "duplicate" and our comparison agrees → - auto-close with "confirmed duplicate of #NNN, thank you" -- **Substitute** (>0.85): bot says "duplicate" but partial match → - auto-draft differentiation, human reviews before posting -- **Control** (<0.85): bot says something unexpected → flag for human - -### Files to Create - -- `lib/feedback_o_tron/bot_handler.ex` — bot detection and response -- `lib/feedback_o_tron/issue_comparator.ex` — deep issue comparison -- `lib/feedback_o_tron/auto_responder.ex` — draft and post responses - ---- - -## 3. Feedback-on-Feedback Loop (Self-Improvement) - -### What It Does - -The Feedback-o-Tron solicits feedback about itself, processes it through -Hypatia's neural networks, and evolves its own behaviour. - -### Architecture - -``` - ┌──────────────────────┐ - │ External Users │ - │ (GitHub, PanLL) │ - └──────────┬───────────┘ - │ feedback - ┌──────────▼───────────┐ - │ Feedback-o-Tron │ - │ (collects, routes) │ - └──────────┬───────────┘ - │ self-feedback - ┌──────────▼───────────┐ - │ Hypatia │ - │ (learns, adapts) │ - │ ESN + RBF networks │ - └──────────┬───────────┘ - │ updated patterns - ┌──────────▼───────────┐ - │ Feedback-o-Tron │ - │ (evolved rules) │ - └──────────────────────┘ -``` - -### Self-Feedback Collection - -After every feedback submission, the Feedback-o-Tron asks: -- Was the report filed to the right place? -- Was the severity assessment accurate? -- Did the pre-flight catch relevant duplicates? -- Did the bot handler respond appropriately? -- Was the outcome satisfactory? - -These answers feed into Hypatia's training pipeline as outcome data, -adjusting the ESN confidence scores for future submissions. - -### Hypatia Correspondence Protocol - -``` -FeedbackOTron -> Hypatia: - - Submit outcome records (success/failure/partial) - - Request pattern analysis ("what types of reports get closed?") - - Receive updated confidence thresholds - -Hypatia -> FeedbackOTron: - - Updated Safety Triangle thresholds per target repo - - Pattern alerts ("issues mentioning X get auto-closed on repo Y") - - Severity calibration adjustments -``` - -### Files to Create - -- `lib/feedback_o_tron/self_feedback.ex` — self-assessment after submissions -- `lib/feedback_o_tron/hypatia_bridge.ex` — bidirectional Hypatia comms -- Extend Hypatia's `training_pipeline.ex` with feedback-o-tron outcome data - ---- - -## 4. Dual-Mode Feedback Collection Forms - -### The Problem - -Humans give brief, high-signal feedback ("this is broken", "love this"). -LLMs/SLMs can give detailed, structured feedback but need prompting. -Currently we only support unstructured text input. - -### Solution: Two Feedback Modes - -#### Mode A: Human Questionnaire (Quick) - -5 questions, ~30 seconds: - -``` -1. What did you use? [dropdown: panel name / tool name / workflow] -2. Did it work? [Yes / Partially / No] -3. How frustrated were you? [1-5 slider → feeds Vexometer] -4. What would you improve? [free text, optional] -5. Would you recommend this? [Yes / Maybe / No → NPS-style] -``` - -Rendered as a clean form in PanLL's Feedback-o-Tron panel. Results -stored as structured JSON in VeriSimDB. - -#### Mode B: LLM/SLM Deep-Dive Questionnaire - -If the user opts in ("Let my AI assistant provide detailed feedback"), -the Feedback-o-Tron sends a structured prompt to the user's local LLM -or cloud provider: - -``` -Prompt: "You have been using [TOOL] version [VERSION] for [DURATION]. -Based on your session, please provide detailed feedback on: - -1. FUNCTIONALITY: Did all features work as documented? List any that - didn't, with reproduction steps. - -2. ERGONOMICS: Rate the cognitive load (1-10). Were error messages - helpful? Was the workflow intuitive? Identify friction points. - -3. PERFORMANCE: Note any latency, hangs, or resource issues. - Include approximate timing if possible. - -4. DOCUMENTATION: Was the documentation sufficient? What was missing? - -5. INTEGRATION: How well did this tool work with other tools in your - workflow? Any compatibility issues? - -6. SUGGESTIONS: Prioritised list of improvements, each with: - - Description - - Severity (critical/high/medium/low) - - Estimated user impact - -7. COMPARISON: If you've used similar tools, how does this compare? - What does it do better/worse? - -Format as JSON for machine processing." -``` - -### Why This Matters - -- Human feedback is high-signal but low-volume (people don't fill forms) -- LLM feedback is lower-signal but high-volume and highly structured -- Combined: humans flag what matters, LLMs fill in the details -- The Feedback-o-Tron can collect 10x more feedback by offering the - LLM option alongside the human one -- SLMs (local models) can provide feedback without API costs - -### Privacy - -- LLM feedback mode is opt-in only -- No session data sent without explicit consent -- Local SLM option means feedback never leaves the user's machine -- All feedback is attributed (human vs LLM) so analysis can weight - accordingly - -### Files to Create - -- `src/components/FeedbackForm.res` — dual-mode form component -- `src/model/FeedbackFormModel.res` — form state types -- `src/core/FeedbackFormEngine.res` — form logic + LLM prompt builder -- `src/commands/FeedbackFormCmd.res` — submission to VeriSimDB - ---- - -## 5. Feedback-o-Tron Self-Invitation - -### What It Does - -The Feedback-o-Tron proactively invites feedback at natural moments: - -- After completing a multi-step workflow -- After filing an issue/PR (was the process smooth?) -- After a tool error or crash recovery -- Periodically (weekly digest prompt) -- After significant version updates - -### Implementation - -Non-intrusive toast notification in PanLL's status bar: -"How was that? [Quick feedback] [Detailed feedback] [Not now]" - -Frequency capped: max 1 invitation per session, max 3 per week. -"Not now" suppresses for 48 hours. - -### Integration with Cognitive Governance - -The Vexometer monitors whether feedback invitations themselves cause -friction. If users consistently dismiss them → reduce frequency. -If users engage → maintain or slightly increase. - ---- - -## Implementation Priority - -1. **Pre-flight duplicate detection** — prevents the exact problem that - triggered this design (highest immediate value) -2. **Bot response handler** — automates the tedious triage work -3. **Human feedback form** — basic structured collection -4. **LLM/SLM feedback mode** — force multiplier for feedback volume -5. **Self-feedback loop** — long-term self-improvement -6. **Hypatia bridge** — closes the learning loop - -## Dependencies - -- Hypatia ESN/RBF training pipeline (exists, 376 tests passing) -- VeriSimDB for feedback storage (exists, connected) -- PanLL TEA framework for form components (exists) -- BoJ cartridge for external API calls (exists) - ---- - -*This design was prompted by GitHub issue anthropics/claude-code#34819, -where the Feedback-o-Tron filed a security report but didn't pre-check -for duplicates, and the subsequent bot interaction had to be handled -manually. Every gap identified here was a real pain point from a single -session.* diff --git a/docs/developer-guide.md b/docs/developer-guide.adoc similarity index 88% rename from docs/developer-guide.md rename to docs/developer-guide.adoc index ceab7bef..4bbaa76f 100644 --- a/docs/developer-guide.md +++ b/docs/developer-guide.adoc @@ -1,27 +1,32 @@ -# PanLL Developer Guide +== PanLL Developer Guide -## Overview +=== Overview -This guide provides comprehensive information for developers who want to extend, customize, or integrate with PanLL's identity management system. Learn how to build plugins, extend the API, and contribute to the core system. +This guide provides comprehensive information for developers who want to +extend, customize, or integrate with PanLL’s identity management system. +Learn how to build plugins, extend the API, and contribute to the core +system. -## Table of Contents +=== Table of Contents -1. [Architecture Overview](#architecture-overview) -2. [Development Environment Setup](#development-environment-setup) -3. [Identity Management API](#identity-management-api) -4. [Extending Identity Management](#extending-identity-management) -5. [Plugin System](#plugin-system) -6. [Custom Storage Backends](#custom-storage-backends) -7. [Testing & Quality Assurance](#testing--quality-assurance) -8. [Performance Optimization](#performance-optimization) -9. [Contributing to Core](#contributing-to-core) -10. [API Reference](#api-reference) +[arabic] +. link:#architecture-overview[Architecture Overview] +. link:#development-environment-setup[Development Environment Setup] +. link:#identity-management-api[Identity Management API] +. link:#extending-identity-management[Extending Identity Management] +. link:#plugin-system[Plugin System] +. link:#custom-storage-backends[Custom Storage Backends] +. link:++#testing--quality-assurance++[Testing & Quality Assurance] +. link:#performance-optimization[Performance Optimization] +. link:#contributing-to-core[Contributing to Core] +. link:#api-reference[API Reference] -## Architecture Overview +=== Architecture Overview -### System Architecture +==== System Architecture -```mermaid +[source,mermaid] +---- graph TD A[Frontend: ReScript/React] -->|IPC| B[Backend: Rust/Gossamer] B -->|FFI| C[Gossamer Shell: Zig] @@ -30,11 +35,11 @@ graph TD B -->|FS| F[Local Storage] D -->|SQLite| G[Database] E -->|WebSocket| H[Team Members] -``` +---- -### Identity Management Components +==== Identity Management Components -``` +.... ┌───────────────────────────────────────────────────┐ │ Identity Management │ ├─────────────────┬─────────────────┬───────────────┤ @@ -52,23 +57,26 @@ graph TD │ VeriSimDB │ Burble │ Custom │ │ API │ Broadcast │ Services │ └─────────────────┴─────────────────┴───────────────┘ -``` +.... -### Key Modules +==== Key Modules -| Module | Language | Purpose | -|--------|----------|---------| -| `identity.rs` | Rust | Core identity operations | -| `identity_cache.rs` | Rust | Caching layer | -| `IdentityService.res` | ReScript | Frontend service | -| `IdentityStore.res` | ReScript | Frontend state management | -| `verisimdb_bridge.rs` | Rust | VeriSimDB integration | +[cols=",,",options="header",] +|=== +|Module |Language |Purpose +|`+identity.rs+` |Rust |Core identity operations +|`+identity_cache.rs+` |Rust |Caching layer +|`+IdentityService.res+` |ReScript |Frontend service +|`+IdentityStore.res+` |ReScript |Frontend state management +|`+verisimdb_bridge.rs+` |Rust |VeriSimDB integration +|=== -## Development Environment Setup +=== Development Environment Setup -### Prerequisites +==== Prerequisites -```bash +[source,bash] +---- # Install system dependencies sudo apt update sudo apt install -y \ @@ -91,13 +99,15 @@ source $HOME/.cargo/env curl -fsSL https://deno.land/x/install/install.sh | sh export DENO_INSTALL="/home/$USER/.deno" export PATH="$DENO_INSTALL/bin:$PATH" -``` +---- -ReScript is pinned in `deno.json` (`npm:rescript@^12.0.0`) and resolved on first `deno task res:build` — no global install required. +ReScript is pinned in `+deno.json+` (`+npm:rescript@^12.0.0+`) and +resolved on first `+deno task res:build+` — no global install required. -### Clone and Build +==== Clone and Build -```bash +[source,bash] +---- # Clone repository git clone https://github.com/hyperpolymath/panll.git cd panll @@ -111,21 +121,22 @@ deno task build # Run in development mode panll --dev -``` +---- -### IDE Setup +==== IDE Setup -#### VS Code Recommended Extensions +===== VS Code Recommended Extensions -- **Rust Analyzer** - Rust language support -- **ReScript** - ReScript language support -- **Deno** - Deno support -- **TOML** - TOML syntax highlighting -- **Even Better TOML** - Enhanced TOML support +* *Rust Analyzer* - Rust language support +* *ReScript* - ReScript language support +* *Deno* - Deno support +* *TOML* - TOML syntax highlighting +* *Even Better TOML* - Enhanced TOML support -#### VS Code Settings +===== VS Code Settings -```json +[source,json] +---- { "rust-analyzer.checkOnSave": true, "rust-analyzer.cargo.runBuildScripts": true, @@ -139,13 +150,14 @@ panll --dev "editor.defaultFormatter": "chrisdavies.rescript-vscode" } } -``` +---- -## Identity Management API +=== Identity Management API -### Core API Endpoints +==== Core API Endpoints -```rust +[source,rust] +---- // src-gossamer/src/main.rs // Save identity snapshot @@ -179,11 +191,12 @@ app.command("team_broadcast_state", |payload| { let snapshot_json = get_str(&payload, "snapshot_json")?; result_to_json(identity::team_broadcast_state(&snapshot_json)) }); -``` +---- -### Frontend API (ReScript) +==== Frontend API (ReScript) -```rescript +[source,rescript] +---- // src/core/IdentityService.res module IdentityService = { @@ -212,11 +225,12 @@ module IdentityService = { ErrorBoundary.invokeWithBoundary("team_broadcast_state", {"snapshot_json": snapshotJson}) }; }; -``` +---- -### Type Definitions +==== Type Definitions -```typescript +[source,typescript] +---- // IdentitySnapshot interface interface IdentitySnapshot { id: string; // UUID v4 @@ -233,13 +247,14 @@ interface ApiResponse { result?: T; error?: string; } -``` +---- -## Extending Identity Management +=== Extending Identity Management -### Adding Custom Fields +==== Adding Custom Fields -```rust +[source,rust] +---- // src-gossamer/src/identity.rs #[derive(Debug, Clone, Serialize, Deserialize)] @@ -261,11 +276,12 @@ pub struct IdentitySnapshot { /// NEW: Tags for categorization pub tags: Option>, } -``` +---- -### Adding New Commands +==== Adding New Commands -```rust +[source,rust] +---- // 1. Add to main.rs app.command("identity_add_tag", |payload| { let id = get_str(&payload, "id")?; @@ -303,11 +319,12 @@ pub fn add_tag(id: &str, tag: &str) -> Result { let addTag = (~id, ~tag) => { ErrorBoundary.invokeWithBoundary("identity_add_tag", {"id": id, "tag": tag}) }; -``` +---- -### Custom Validation +==== Custom Validation -```rust +[source,rust] +---- // Add validation function pub fn validate_snapshot(snapshot: &IdentitySnapshot) -> Result<(), String> { // Check name length @@ -342,13 +359,13 @@ pub fn identity_save(...) -> Result { validate_snapshot(&snapshot)?; // ... rest of implementation } -``` +---- -## Plugin System +=== Plugin System -### Plugin Architecture +==== Plugin Architecture -``` +.... ┌───────────────────────────────────────────────────┐ │ Plugin System │ ├─────────────────┬─────────────────┬───────────────┤ @@ -363,11 +380,12 @@ pub fn identity_save(...) -> Result { │ Storage │ Processing │ UI │ │ Plugins │ Plugins │ Extensions │ └─────────────────┴─────────────────┴───────────────┘ -``` +.... -### Plugin Interface +==== Plugin Interface -```rust +[source,rust] +---- // src-gossamer/src/plugins/mod.rs pub trait IdentityPlugin: Send + Sync { @@ -392,11 +410,12 @@ pub struct PluginConfig { pub cache_dir: PathBuf, pub config: serde_json::Value, } -``` +---- -### Creating a Storage Plugin +==== Creating a Storage Plugin -```rust +[source,rust] +---- // Example: S3 Storage Plugin use async_trait::async_trait; use aws_sdk_s3::Client; @@ -483,11 +502,12 @@ impl S3StoragePlugin { // Implement load_snapshot, delete_snapshot, list_snapshots... } -``` +---- -### Plugin Registration +==== Plugin Registration -```rust +[source,rust] +---- // src-gossamer/src/main.rs mod plugins; @@ -520,11 +540,12 @@ fn main() { }); } } -``` +---- -### Frontend Plugin Integration +==== Frontend Plugin Integration -```rescript +[source,rescript] +---- // src/core/PluginManager.res module PluginManager = { @@ -554,13 +575,14 @@ module PluginManager = { ) }; }; -``` +---- -## Custom Storage Backends +=== Custom Storage Backends -### Storage Backend Interface +==== Storage Backend Interface -```rust +[source,rust] +---- // src-gossamer/src/storage/mod.rs pub trait IdentityStorage: Send + Sync { @@ -588,11 +610,12 @@ pub struct StorageStats { pub total_size_bytes: u64, pub storage_type: String, } -``` +---- -### Implementing a Custom Backend +==== Implementing a Custom Backend -```rust +[source,rust] +---- // Example: PostgreSQL Storage Backend use sqlx::postgres::PgPoolOptions; use sqlx::{PgPool, Postgres, Transaction}; @@ -700,11 +723,12 @@ impl IdentityStorage for PostgresStorage { } } } -``` +---- -### Storage Backend Configuration +==== Storage Backend Configuration -```toml +[source,toml] +---- # storage.toml [storage] # Primary storage backend @@ -731,11 +755,12 @@ prefix = "identities" [storage.postgres] enabled = false connection_string = "postgres://user:pass@localhost/panll" -``` +---- -### Multi-Backend Strategy +==== Multi-Backend Strategy -```rust +[source,rust] +---- // src-gossamer/src/storage/strategy.rs pub struct MultiBackendStorage { @@ -795,13 +820,14 @@ impl MultiBackendStorage { } } } -``` +---- -## Testing & Quality Assurance +=== Testing & Quality Assurance -### Unit Testing +==== Unit Testing -```rust +[source,rust] +---- // tests/identity_tests.rs #[cfg(test)] @@ -882,11 +908,12 @@ mod tests { assert!(result.is_ok()); } } -``` +---- -### Integration Testing +==== Integration Testing -```javascript +[source,javascript] +---- // tests/identity_integration_test.js import { assert, assertEquals } from "https://deno.land/std/testing/asserts.ts"; import { invoke } from "../src/ipc/ipc.js"; @@ -913,11 +940,12 @@ Deno.test("Custom storage backend integration", async (t) => { assertEquals(statsData.primary, "postgres"); }); }); -``` +---- -### Performance Testing +==== Performance Testing -```rust +[source,rust] +---- // benchmarks/identity_benchmarks.rs #[bench] @@ -960,11 +988,12 @@ fn bench_batch_operations(b: &mut Bencher) { batch_save_snapshots(&snapshots, &storage).unwrap(); }); } -``` +---- -### Test Coverage +==== Test Coverage -```bash +[source,bash] +---- # Run all tests cargo test --all-features @@ -982,13 +1011,14 @@ cargo test --test integration_tests # Run benchmarks cargo bench -``` +---- -## Performance Optimization +=== Performance Optimization -### Caching Strategies +==== Caching Strategies -```rust +[source,rust] +---- // src-gossamer/src/identity_cache.rs use lru::LruCache; @@ -1040,11 +1070,12 @@ impl IdentityCache { } } } -``` +---- -### Batch Processing +==== Batch Processing -```rust +[source,rust] +---- // src-gossamer/src/batch.rs pub async fn batch_save_snapshots( @@ -1103,11 +1134,12 @@ pub async fn batch_save_snapshots( } }) } -``` +---- -### Performance Monitoring +==== Performance Monitoring -```rust +[source,rust] +---- // src-gossamer/src/metrics.rs pub struct IdentityMetrics { @@ -1181,24 +1213,26 @@ impl IdentityMetrics { self.cache_misses.store(0, Ordering::Relaxed); } } -``` +---- -### Performance Tips +==== Performance Tips -1. **Caching**: Implement LRU cache with 256MB capacity -2. **Batching**: Use batch operations for bulk actions -3. **Compression**: Enable for snapshots >10KB -4. **Connection Pooling**: Reuse database connections -5. **Parallel Processing**: Use tokio for async I/O -6. **Lazy Loading**: Load only necessary data -7. **Pagination**: Implement for large result sets -8. **Debouncing**: For rapid UI updates +[arabic] +. *Caching*: Implement LRU cache with 256MB capacity +. *Batching*: Use batch operations for bulk actions +. *Compression*: Enable for snapshots >10KB +. *Connection Pooling*: Reuse database connections +. *Parallel Processing*: Use tokio for async I/O +. *Lazy Loading*: Load only necessary data +. *Pagination*: Implement for large result sets +. *Debouncing*: For rapid UI updates -## Contributing to Core +=== Contributing to Core -### Contribution Guidelines +==== Contribution Guidelines -```markdown +[source,markdown] +---- # Contributing to PanLL ## Getting Started @@ -1276,11 +1310,12 @@ impl IdentityMetrics { ## License By contributing, you agree to license your contributions under the MPL-2.0. -``` +---- -### Development Workflow +==== Development Workflow -```bash +[source,bash] +---- # Setup git clone https://github.com/your-fork/panll.git cd panll @@ -1305,18 +1340,20 @@ git push origin feature/your-feature-name # Create pull request gh pr create --base main --head your-fork:feature/your-feature-name -``` +---- -### Code Review Process +==== Code Review Process -1. **Automated Checks**: CI runs tests and lints -2. **Peer Review**: At least one approval required -3. **Maintainer Review**: Architecture and design review -4. **Merge**: After all checks pass +[arabic] +. *Automated Checks*: CI runs tests and lints +. *Peer Review*: At least one approval required +. *Maintainer Review*: Architecture and design review +. *Merge*: After all checks pass -### Continuous Integration +==== Continuous Integration -```yaml +[source,yaml] +---- # .github/workflows/ci.yml name: CI @@ -1365,13 +1402,14 @@ jobs: - name: Build frontend run: deno task build -``` +---- -## API Reference +=== API Reference -### Core Identity API +==== Core Identity API -```typescript +[source,typescript] +---- // Save identity snapshot interface SaveIdentityParams { name: string; @@ -1390,11 +1428,12 @@ interface SaveIdentityResult { } async function identitySave(params: SaveIdentityParams): Promise>; -``` +---- -### Storage Plugin API +==== Storage Plugin API -```typescript +[source,typescript] +---- interface StoragePlugin { name: string; version: string; @@ -1411,11 +1450,12 @@ async function registerStoragePlugin(plugin: StoragePlugin): Promise; // Unregister plugin async function unregisterStoragePlugin(name: string): Promise; -``` +---- -### Batch Operations API +==== Batch Operations API -```typescript +[source,typescript] +---- interface BatchOperationResult { success: T[]; failures: { id: string; error: string }[]; @@ -1438,11 +1478,12 @@ async function batchLoadSnapshots( async function batchDeleteSnapshots( ids: string[] ): Promise>; -``` +---- -### Cache Management API +==== Cache Management API -```typescript +[source,typescript] +---- interface CacheStats { size: number; capacity: number; @@ -1454,14 +1495,15 @@ async function getCacheStats(): Promise>; async function clearCache(): Promise>; async function setCacheSize(sizeMb: number): Promise>; -``` +---- -## Conclusion +=== Conclusion -This developer guide provides comprehensive information for extending PanLL's identity management system. Whether you're building plugins, custom storage backends, or contributing to the core system, this guide covers the architecture, APIs, and best practices you'll need. +This developer guide provides comprehensive information for extending +PanLL’s identity management system. Whether you’re building plugins, +custom storage backends, or contributing to the core system, this guide +covers the architecture, APIs, and best practices you’ll need. -For more information: -- **API Reference**: Complete API documentation -- **Admin Guide**: Deployment and configuration -- **User Guide**: Using identity management features -- **GitHub**: Source code and issue tracker \ No newline at end of file +For more information: - *API Reference*: Complete API documentation - +*Admin Guide*: Deployment and configuration - *User Guide*: Using +identity management features - *GitHub*: Source code and issue tracker diff --git a/docs/guides/QUICKSTART-FOR-SON.adoc b/docs/guides/QUICKSTART-FOR-SON.adoc new file mode 100644 index 00000000..d4555a27 --- /dev/null +++ b/docs/guides/QUICKSTART-FOR-SON.adoc @@ -0,0 +1,190 @@ +== PanLL Quickstart Guide + +=== What is PanLL? + +PanLL is a developer environment with three main panels side-by-side: + +* *Panel L (left, indigo)* – Symbolic/logic constraints. Think of it +like rules the system must follow. +* *Panel N (middle, green)* – Neural stream. This is where AI inference +happens, tokens flow through, and the OODA loop runs. +* *Panel W (right)* – World state. Security tools, event chains, +database queries. + +On top of these, there are *overlay panels* you can open from the panel +bar (vertical icons on the right edge). + +=== How to Run + +[source,bash] +---- +cd ~/Documents/hyperpolymath-repos/panll + +# Terminal 1: Start the ReScript compiler (watches for changes) +deno task res:watch + +# Terminal 2: Bundle the JS and serve +just bundle && just serve:dev + +# Terminal 3: Build Tailwind CSS +just css:build + +# Terminal 4: Start the Gossamer backend +cargo run --bin panll-gossamer +---- + +Or for the full dev experience: + +[source,bash] +---- +# In the panll directory: +just dev +---- + +The app opens at `+http://localhost:8000/public/+` (Gossamer wraps +this). + +=== First Thing You See + +A dark screen with two circles (SYMBOLIC and NEURAL) connected by a +dotted line. *Click anywhere* to enter the environment. + +=== Panel Bar (right edge) + +The vertical strip of icons on the right edge is the *panel bar*. Click +any icon to open that panel as a full-screen overlay. Click again (or +press Escape) to close. + +*Interesting panels to try:* + +[width="100%",cols="24%,26%,50%",options="header",] +|=== +|Icon |Panel |What it does +|VAB |Verified Assembly Building |Like KSP’s Vehicle Assembly Building +but for servers. Pick components, see what capabilities you get. Really +fun to play with! + +|Sec |Security |Secrets detection, vault, 2FA, shoulder-safe mode (blurs +secrets). Toggle "`Shoulder-Safe`" for a laugh. + +|Cap |Capture |Screenshot any panel, record sessions, create demos for +teaching. + +|WS |Workspace |Change the workspace mode +(Rhodium/Everything/Code/Bespoke), set protection levels, manage +layouts. + +|AI |AI |Multi-provider AI chat (needs API keys configured). +|=== + +=== VAB (Verified Assembly Building) – The Fun One + +This is inspired by Kerbal Space Program’s VAB. You’re building a server +by picking components: + +[arabic] +. Open VAB from the panel bar +. Browse categories: Core, Network, DNS, Web, IoT, Email, Security, +Data, Application, Infrastructure, Connectors +. Click components to add them to your server +. Watch the *warnings* and *capabilities* update in real-time +. It tells you what your server CAN and CANNOT do based on what +components you’ve added +. Missing dependencies show as warnings (like "`Missing TLS +component!`") + +There are *111 proven-servers components* in the catalog. Try building +different server configs! + +=== Security Panel – Working Together Mode + +The Security panel has features designed for group work: + +* *Shoulder-Safe Mode*: Blurs detected secrets. Toggle it on and API +keys get masked in real-time. +* *Redaction Patterns*: 10 built-in patterns detect API keys (Anthropic, +OpenAI, AWS, GitHub, etc.). +* *2FA*: TOTP-based authentication for sensitive operations. +* *Trustfile*: Per-repo security policies loaded from +`+Trustfile.a2ml+`. + +=== Workspace Modes + +Press *Ctrl+Shift+M* to cycle through modes: + +* *Rhodium*: Everything visible, full compliance view +* *Everything*: All panels, all tools +* *Code*: Pure coding – hides governance panels +* *Bespoke*: Custom per-repo setup + +=== Session Protection + +These control what you can do: + +* *Open*: Normal, do whatever +* *Read-Only*: Look but don’t touch +* *Sandboxed*: Do whatever, but it all resets when you leave +* *Language-Locked*: Specific file types can’t be edited (e.g., lock all +`+.idr+` files) +* *Transpilation-Guarded*: Must prove your change produces equivalent +output before saving +* *Production-Gated*: Changes need sign-off before they take effect + +=== Keyboard Shortcuts + +[cols=",",options="header",] +|=== +|Shortcut |Action +|Ctrl+Z |Undo +|Ctrl+Shift+Z |Redo +|Ctrl+S |Save state +|Ctrl+P |Print active panel +|Ctrl+Shift+L |Toggle Panel L +|Ctrl+Shift+N |Toggle Panel N +|Ctrl+Shift+B/W |Toggle Panel W +|Ctrl+Shift+C |Open Capture panel +|Ctrl+Shift+K |Open Workspace panel +|Ctrl+Shift+S |Open Security panel +|Ctrl+Shift+M |Cycle workspace mode +|Ctrl+Shift+D |Toggle dry-run mode +|Escape |Close current panel +|=== + +All shortcuts are *remappable* via the Workspace panel’s Keybindings +section. + +=== Capture Bar (side icons on panels) + +Each panel has a small vertical strip of icons on its right edge: + +* *C* = Screenshot this panel +* *R* = Record this panel +* *D* = Clone this panel (independent copy) +* *=* = Compare this panel with another + +=== Status Bar (bottom) + +Shows: active panel, workspace mode, execution mode, repo name, AI +status, CPU/memory usage, uptime. + +=== The Cool Concepts + +* *Contractiles*: Elastic state contracts that govern the system. If +vexation gets too high, the system intervenes. +* *Vexometer*: Tracks how frustrated the operator is. Visible as a small +bar. +* *Orbital Drift Aura*: The background colour changes based on system +stability. +* *Anti-Crash*: A circuit breaker that validates all neural tokens +against symbolic constraints. +* *Dry Run mode*: Preview changes without applying them. +* *Forked sessions*: Create independent copies of your workspace. + +=== Tech Stack + +* *Frontend*: ReScript (compiles to JavaScript) with custom TEA (The Elm +Architecture) +* *Backend*: Rust via Tauri 2.0 +* *Styling*: Tailwind CSS +* *Runtime*: Deno (not Node) +* *Tests*: 97 passing diff --git a/docs/guides/QUICKSTART-FOR-SON.md b/docs/guides/QUICKSTART-FOR-SON.md deleted file mode 100644 index 807ff687..00000000 --- a/docs/guides/QUICKSTART-FOR-SON.md +++ /dev/null @@ -1,147 +0,0 @@ -# PanLL Quickstart Guide - -## What is PanLL? - -PanLL is a developer environment with three main panels side-by-side: - -- **Panel L (left, indigo)** -- Symbolic/logic constraints. Think of it like rules the system must follow. -- **Panel N (middle, green)** -- Neural stream. This is where AI inference happens, tokens flow through, and the OODA loop runs. -- **Panel W (right)** -- World state. Security tools, event chains, database queries. - -On top of these, there are **overlay panels** you can open from the panel bar (vertical icons on the right edge). - -## How to Run - -```bash -cd ~/Documents/hyperpolymath-repos/panll - -# Terminal 1: Start the ReScript compiler (watches for changes) -deno task res:watch - -# Terminal 2: Bundle the JS and serve -just bundle && just serve:dev - -# Terminal 3: Build Tailwind CSS -just css:build - -# Terminal 4: Start the Gossamer backend -cargo run --bin panll-gossamer -``` - -Or for the full dev experience: -```bash -# In the panll directory: -just dev -``` - -The app opens at `http://localhost:8000/public/` (Gossamer wraps this). - -## First Thing You See - -A dark screen with two circles (SYMBOLIC and NEURAL) connected by a dotted line. **Click anywhere** to enter the environment. - -## Panel Bar (right edge) - -The vertical strip of icons on the right edge is the **panel bar**. Click any icon to open that panel as a full-screen overlay. Click again (or press Escape) to close. - -**Interesting panels to try:** - -| Icon | Panel | What it does | -|------|-------|-------------| -| VAB | Verified Assembly Building | Like KSP's Vehicle Assembly Building but for servers. Pick components, see what capabilities you get. Really fun to play with! | -| Sec | Security | Secrets detection, vault, 2FA, shoulder-safe mode (blurs secrets). Toggle "Shoulder-Safe" for a laugh. | -| Cap | Capture | Screenshot any panel, record sessions, create demos for teaching. | -| WS | Workspace | Change the workspace mode (Rhodium/Everything/Code/Bespoke), set protection levels, manage layouts. | -| AI | AI | Multi-provider AI chat (needs API keys configured). | - -## VAB (Verified Assembly Building) -- The Fun One - -This is inspired by Kerbal Space Program's VAB. You're building a server by picking components: - -1. Open VAB from the panel bar -2. Browse categories: Core, Network, DNS, Web, IoT, Email, Security, Data, Application, Infrastructure, Connectors -3. Click components to add them to your server -4. Watch the **warnings** and **capabilities** update in real-time -5. It tells you what your server CAN and CANNOT do based on what components you've added -6. Missing dependencies show as warnings (like "Missing TLS component!") - -There are **111 proven-servers components** in the catalog. Try building different server configs! - -## Security Panel -- Working Together Mode - -The Security panel has features designed for group work: - -- **Shoulder-Safe Mode**: Blurs detected secrets. Toggle it on and API keys get masked in real-time. -- **Redaction Patterns**: 10 built-in patterns detect API keys (Anthropic, OpenAI, AWS, GitHub, etc.). -- **2FA**: TOTP-based authentication for sensitive operations. -- **Trustfile**: Per-repo security policies loaded from `Trustfile.a2ml`. - -## Workspace Modes - -Press **Ctrl+Shift+M** to cycle through modes: - -- **Rhodium**: Everything visible, full compliance view -- **Everything**: All panels, all tools -- **Code**: Pure coding -- hides governance panels -- **Bespoke**: Custom per-repo setup - -## Session Protection - -These control what you can do: - -- **Open**: Normal, do whatever -- **Read-Only**: Look but don't touch -- **Sandboxed**: Do whatever, but it all resets when you leave -- **Language-Locked**: Specific file types can't be edited (e.g., lock all `.idr` files) -- **Transpilation-Guarded**: Must prove your change produces equivalent output before saving -- **Production-Gated**: Changes need sign-off before they take effect - -## Keyboard Shortcuts - -| Shortcut | Action | -|----------|--------| -| Ctrl+Z | Undo | -| Ctrl+Shift+Z | Redo | -| Ctrl+S | Save state | -| Ctrl+P | Print active panel | -| Ctrl+Shift+L | Toggle Panel L | -| Ctrl+Shift+N | Toggle Panel N | -| Ctrl+Shift+B/W | Toggle Panel W | -| Ctrl+Shift+C | Open Capture panel | -| Ctrl+Shift+K | Open Workspace panel | -| Ctrl+Shift+S | Open Security panel | -| Ctrl+Shift+M | Cycle workspace mode | -| Ctrl+Shift+D | Toggle dry-run mode | -| Escape | Close current panel | - -All shortcuts are **remappable** via the Workspace panel's Keybindings section. - -## Capture Bar (side icons on panels) - -Each panel has a small vertical strip of icons on its right edge: - -- **C** = Screenshot this panel -- **R** = Record this panel -- **D** = Clone this panel (independent copy) -- **=** = Compare this panel with another - -## Status Bar (bottom) - -Shows: active panel, workspace mode, execution mode, repo name, AI status, CPU/memory usage, uptime. - -## The Cool Concepts - -- **Contractiles**: Elastic state contracts that govern the system. If vexation gets too high, the system intervenes. -- **Vexometer**: Tracks how frustrated the operator is. Visible as a small bar. -- **Orbital Drift Aura**: The background colour changes based on system stability. -- **Anti-Crash**: A circuit breaker that validates all neural tokens against symbolic constraints. -- **Dry Run mode**: Preview changes without applying them. -- **Forked sessions**: Create independent copies of your workspace. - -## Tech Stack - -- **Frontend**: ReScript (compiles to JavaScript) with custom TEA (The Elm Architecture) -- **Backend**: Rust via Tauri 2.0 -- **Styling**: Tailwind CSS -- **Runtime**: Deno (not Node) -- **Tests**: 97 passing diff --git a/docs/guides/TEA_GUIDE.md b/docs/guides/TEA_GUIDE.adoc similarity index 62% rename from docs/guides/TEA_GUIDE.md rename to docs/guides/TEA_GUIDE.adoc index 70f0294a..b21660bd 100644 --- a/docs/guides/TEA_GUIDE.md +++ b/docs/guides/TEA_GUIDE.adoc @@ -1,108 +1,132 @@ -# The Elm Architecture (TEA) Guide for PanLL +== The Elm Architecture (TEA) Guide for PanLL -**Version:** 2.0.0 -**Status:** Production Ready — Permanent Custom Implementation -**License:** MPL-2.0 -**Author:** Jonathan D.A. Jewell +*Version:* 2.0.0 *Status:* Production Ready — Permanent Custom +Implementation *License:* MPL-2.0 *Author:* Jonathan D.A. Jewell +j.d.a.jewell@open.ac.uk -## Table of Contents +=== Table of Contents -- [Introduction](#introduction) -- [Permanence Decision](#permanence-decision) -- [Module Inventory](#module-inventory) -- [Core Concepts](#core-concepts) -- [Module Reference](#module-reference) -- [Architecture Guide](#architecture-guide) -- [Testing](#testing) -- [Best Practices](#best-practices) -- [Examples](#examples) +* link:#introduction[Introduction] +* link:#permanence-decision[Permanence Decision] +* link:#module-inventory[Module Inventory] +* link:#core-concepts[Core Concepts] +* link:#module-reference[Module Reference] +* link:#architecture-guide[Architecture Guide] +* link:#testing[Testing] +* link:#best-practices[Best Practices] +* link:#examples[Examples] ---- +''''' -## Introduction +=== Introduction -The Elm Architecture (TEA) is a pattern for building web applications that provides: +The Elm Architecture (TEA) is a pattern for building web applications +that provides: -- **Predictable state management**: All state changes flow through a single update function -- **Side-effect isolation**: Commands and subscriptions handle async operations -- **Type safety**: ReScript's type system ensures correctness -- **Testability**: Pure functions make testing straightforward +* *Predictable state management*: All state changes flow through a +single update function +* *Side-effect isolation*: Commands and subscriptions handle async +operations +* *Type safety*: ReScript’s type system ensures correctness +* *Testability*: Pure functions make testing straightforward -### Why TEA for PanLL? +==== Why TEA for PanLL? -PanLL (eNSAID - Environment for NeSy-Agentic Integrated Development) requires: -- Complex state management for multi-panel neurosymbolic reasoning -- Real-time updates from agents -- Predictable behavior for debugging reasoning chains -- Type-safe guarantees for critical operations +PanLL (eNSAID - Environment for NeSy-Agentic Integrated Development) +requires: - Complex state management for multi-panel neurosymbolic +reasoning - Real-time updates from agents - Predictable behavior for +debugging reasoning chains - Type-safe guarantees for critical +operations TEA provides all of these guarantees. ---- - -## Permanence Decision - -**Status: PERMANENT — this is not a temporary fork or stopgap.** - -PanLL's custom TEA implementation in `src/tea/` (8 modules, ~700 lines) is the -permanent architecture. The earlier plan to migrate to the official -`rescript-tea@0.16.0` package has been abandoned. The migration guides -(`MIGRATION-TO-RESCRIPT-TEA.md` and `RESCRIPT-TEA-MIGRATION-GUIDE.md`) are -superseded by this document. - -### Why Not Official rescript-tea? - -1. **Unmaintained upstream** — `rescript-tea` has not been updated since 2021. - It depends on `rescript-webapi@0.7.0`, which is incompatible with - ReScript 11.1.4+. -2. **No keyboard subscriptions** — PanLL needs custom keyboard handling - (panel switching, shortcuts). Official rescript-tea has no built-in keyboard - support, so custom subscription code is needed regardless. -3. **Tauri integration** — PanLL's command layer wraps Tauri IPC calls. - Official rescript-tea's command model doesn't account for desktop bridge - APIs. -4. **ARIA accessibility** — Our `Tea_Vdom` has first-class ARIA attribute - support (12+ aria-* helpers, role, tabIndex) built directly into the - attribute type. Official rescript-tea requires manual `property` calls. -5. **VDOM diffing** — Our `Tea_Render` includes a complete diff/patch engine - (Replace, UpdateProps, UpdateChildren, RemoveNode) with event listener - lifecycle management. This would need to be reimplemented on top of - rescript-tea anyway. -6. **Message queue** — `Tea_App` implements a dispatch queue that prevents - recursive dispatch, which is critical for PanLL's multi-panel architecture - where one panel's update can trigger messages in another. -7. **Zero dependencies** — The custom TEA has no npm dependencies at all. - It compiles with ReScript alone and runs in any browser or Tauri webview. - -### What This Means - -- `src/tea/` is a first-class PanLL subsystem, not a vendored fork. -- New features (WebSocket subscriptions, navigation, batch rendering) are - added directly to these modules. -- Bug fixes and optimisations are made in-place. -- The `MIGRATION-TO-RESCRIPT-TEA.md` and `RESCRIPT-TEA-MIGRATION-GUIDE.md` - files in the repo root are historical artefacts and should not be followed. - ---- - -## Module Inventory - -| Module | Lines | Purpose | -|--------|-------|---------| -| `Tea.res` | 25 | Facade — re-exports all TEA modules | -| `Tea_App.res` | 173 | Core runtime: `standardProgram`, `simpleProgram`, dispatch loop, message queue | -| `Tea_Cmd.res` | 61 | Commands: `None`, `Msg`, `Batch`, `Call` with `map`/`execute` | -| `Tea_Sub.res` | 76 | Subscriptions: key-based diffing, `enable`/`cleanup` lifecycle | -| `Tea_Vdom.res` | 106 | Virtual DOM: `Text`/`Element` nodes, attributes (Property, Style, Event, EventWithValue, EventWithKey), ARIA | -| `Tea_Html.res` | 111 | HTML element constructors (37 elements) + `Attrs` and `Events` sub-modules | -| `Tea_Render.res` | 405 | DOM rendering: `createElement`, `diff`, `applyPatch`, event listener tracking, `mount`/`unmount` | -| `Tea_Time.res` | 30 | Time subscriptions: `every` (interval), `after` (timeout) | -| `Tea_Animationframe.res` | 24 | `requestAnimationFrame` subscription | -| **Total** | **~1011** | **Complete TEA implementation with VDOM diffing** | - -### Dependency Graph - -``` +''''' + +=== Permanence Decision + +*Status: PERMANENT — this is not a temporary fork or stopgap.* + +PanLL’s custom TEA implementation in `+src/tea/+` (8 modules, ~700 +lines) is the permanent architecture. The earlier plan to migrate to the +official `+rescript-tea@0.16.0+` package has been abandoned. The +migration guides (`+MIGRATION-TO-RESCRIPT-TEA.md+` and +`+RESCRIPT-TEA-MIGRATION-GUIDE.md+`) are superseded by this document. + +==== Why Not Official rescript-tea? + +[arabic] +. *Unmaintained upstream* — `+rescript-tea+` has not been updated since +2021. It depends on `+rescript-webapi@0.7.0+`, which is incompatible +with ReScript 11.1.4+. +. *No keyboard subscriptions* — PanLL needs custom keyboard handling +(panel switching, shortcuts). Official rescript-tea has no built-in +keyboard support, so custom subscription code is needed regardless. +. *Tauri integration* — PanLL’s command layer wraps Tauri IPC calls. +Official rescript-tea’s command model doesn’t account for desktop bridge +APIs. +. *ARIA accessibility* — Our `+Tea_Vdom+` has first-class ARIA attribute +support (12+ aria-* helpers, role, tabIndex) built directly into the +attribute type. Official rescript-tea requires manual `+property+` +calls. +. *VDOM diffing* — Our `+Tea_Render+` includes a complete diff/patch +engine (Replace, UpdateProps, UpdateChildren, RemoveNode) with event +listener lifecycle management. This would need to be reimplemented on +top of rescript-tea anyway. +. *Message queue* — `+Tea_App+` implements a dispatch queue that +prevents recursive dispatch, which is critical for PanLL’s multi-panel +architecture where one panel’s update can trigger messages in another. +. *Zero dependencies* — The custom TEA has no npm dependencies at all. +It compiles with ReScript alone and runs in any browser or Tauri +webview. + +==== What This Means + +* `+src/tea/+` is a first-class PanLL subsystem, not a vendored fork. +* New features (WebSocket subscriptions, navigation, batch rendering) +are added directly to these modules. +* Bug fixes and optimisations are made in-place. +* The `+MIGRATION-TO-RESCRIPT-TEA.md+` and +`+RESCRIPT-TEA-MIGRATION-GUIDE.md+` files in the repo root are +historical artefacts and should not be followed. + +''''' + +=== Module Inventory + +[width="100%",cols="34%,29%,37%",options="header",] +|=== +|Module |Lines |Purpose +|`+Tea.res+` |25 |Facade — re-exports all TEA modules + +|`+Tea_App.res+` |173 |Core runtime: `+standardProgram+`, +`+simpleProgram+`, dispatch loop, message queue + +|`+Tea_Cmd.res+` |61 |Commands: `+None+`, `+Msg+`, `+Batch+`, `+Call+` +with `+map+`/`+execute+` + +|`+Tea_Sub.res+` |76 |Subscriptions: key-based diffing, +`+enable+`/`+cleanup+` lifecycle + +|`+Tea_Vdom.res+` |106 |Virtual DOM: `+Text+`/`+Element+` nodes, +attributes (Property, Style, Event, EventWithValue, EventWithKey), ARIA + +|`+Tea_Html.res+` |111 |HTML element constructors (37 elements) + +`+Attrs+` and `+Events+` sub-modules + +|`+Tea_Render.res+` |405 |DOM rendering: `+createElement+`, `+diff+`, +`+applyPatch+`, event listener tracking, `+mount+`/`+unmount+` + +|`+Tea_Time.res+` |30 |Time subscriptions: `+every+` (interval), +`+after+` (timeout) + +|`+Tea_Animationframe.res+` |24 |`+requestAnimationFrame+` subscription + +|*Total* |*~1011* |*Complete TEA implementation with VDOM diffing* +|=== + +==== Dependency Graph + +.... Tea.res (facade) ├── Tea_App.res ──────→ Tea_Cmd.res │ │ Tea_Sub.res @@ -110,40 +134,42 @@ Tea.res (facade) ├── Tea_Html.res ──────→ Tea_Vdom.res ├── Tea_Time.res ──────→ Tea_Sub.res └── Tea_Animationframe.res → Tea_Sub.res -``` +.... -No circular dependencies. `Tea_Vdom` is the leaf module. +No circular dependencies. `+Tea_Vdom+` is the leaf module. ---- +''''' -## Core Concepts +=== Core Concepts -### The TEA Cycle +==== The TEA Cycle -``` +.... User Input → Message → Update (Model + Command) → View → DOM ↑ └──────── Subscriptions ────────────────────┘ -``` +.... -### Four Core Components +==== Four Core Components -1. **Model**: Application state (immutable data structure) -2. **Update**: State transition function `(Model, Msg) → (Model, Cmd)` -3. **View**: Rendering function `Model → VirtualDOM` -4. **Subscriptions**: External event sources `Model → Sub` +[arabic] +. *Model*: Application state (immutable data structure) +. *Update*: State transition function `+(Model, Msg) → (Model, Cmd)+` +. *View*: Rendering function `+Model → VirtualDOM+` +. *Subscriptions*: External event sources `+Model → Sub+` ---- +''''' -## Module Reference +=== Module Reference -### Tea_Cmd - Commands +==== Tea_Cmd - Commands Commands represent side effects to be executed after an update. -#### API +===== API -```rescript +[source,rescript] +---- // SPDX-License-Identifier: CC-BY-SA-4.0 type t<'msg> // Opaque command type @@ -159,22 +185,28 @@ let execute: (t<'msg>, 'msg => unit) => unit // Mapping let map: (t<'msg>, 'msg => 'mappedMsg) => t<'mappedMsg> -``` +---- -#### Usage Examples +===== Usage Examples -**No-op command:** -```rescript +*No-op command:* + +[source,rescript] +---- let (newModel, cmd) = (model, Tea_Cmd.none) -``` +---- + +*Immediate message:* -**Immediate message:** -```rescript +[source,rescript] +---- let (model, Tea_Cmd.msg(LoadComplete)) -``` +---- -**Async operation:** -```rescript +*Async operation:* + +[source,rescript] +---- let fetchUserCmd = Tea_Cmd.call(callbacks => { Fetch.get("/api/user") ->Promise.then(response => { @@ -183,22 +215,25 @@ let fetchUserCmd = Tea_Cmd.call(callbacks => { }) ->ignore }) -``` +---- + +*Batch multiple commands:* -**Batch multiple commands:** -```rescript +[source,rescript] +---- let (model, Tea_Cmd.batch(list{ Tea_Cmd.msg(LogEvent("Startup")), Tea_Cmd.call(loadUserData), Tea_Cmd.call(connectWebSocket) })) -``` +---- -#### Testing +===== Testing Commands are easily testable: -```javascript +[source,javascript] +---- // SPDX-License-Identifier: CC-BY-SA-4.0 import { assertEquals } from "@std/assert"; import { msg, execute } from '../src/tea/Tea_Cmd.res.js'; @@ -212,17 +247,19 @@ Deno.test('executes Msg command', () => { assertEquals(dispatched, message); }); -``` +---- ---- +''''' -### Tea_Sub - Subscriptions +==== Tea_Sub - Subscriptions -Subscriptions represent ongoing event sources (WebSocket, timers, keyboard). +Subscriptions represent ongoing event sources (WebSocket, timers, +keyboard). -#### API +===== API -```rescript +[source,rescript] +---- // SPDX-License-Identifier: CC-BY-SA-4.0 type t<'msg> // Opaque subscription type @@ -238,17 +275,21 @@ let getKeys: t<'msg> => array // Mapping let map: (t<'msg>, 'msg => 'mappedMsg) => t<'mappedMsg> -``` +---- -#### Usage Examples +===== Usage Examples -**No subscriptions:** -```rescript +*No subscriptions:* + +[source,rescript] +---- let subscriptions = _model => Tea_Sub.none -``` +---- + +*Timer subscription:* -**Timer subscription:** -```rescript +[source,rescript] +---- let subscriptions = model => { Tea_Sub.registration("timer", dispatch => { let intervalId = setInterval(() => { @@ -259,10 +300,12 @@ let subscriptions = model => { () => clearInterval(intervalId) }) } -``` +---- -**WebSocket subscription:** -```rescript +*WebSocket subscription:* + +[source,rescript] +---- let subscriptions = model => { if model.connected { Tea_Sub.registration("websocket", dispatch => { @@ -279,10 +322,12 @@ let subscriptions = model => { Tea_Sub.none } } -``` +---- + +*Batch subscriptions:* -**Batch subscriptions:** -```rescript +[source,rescript] +---- let subscriptions = model => { Tea_Sub.batch(list{ keyboardSub(model), @@ -290,13 +335,14 @@ let subscriptions = model => { websocketSub(model) }) } -``` +---- -#### Memory Safety +===== Memory Safety -Subscriptions **must** return cleanup functions to prevent memory leaks: +Subscriptions *must* return cleanup functions to prevent memory leaks: -```rescript +[source,rescript] +---- // ✓ CORRECT - cleanup function returned Tea_Sub.registration("timer", dispatch => { let id = setInterval(() => dispatch(Tick), 1000) @@ -308,11 +354,12 @@ Tea_Sub.registration("timer", dispatch => { setInterval(() => dispatch(Tick), 1000) () => () // No cleanup! }) -``` +---- -#### Testing +===== Testing -```javascript +[source,javascript] +---- // SPDX-License-Identifier: CC-BY-SA-4.0 import { assertEquals } from "@std/assert"; @@ -336,17 +383,18 @@ Deno.test('prevents memory leaks with timers', async () => { assertEquals(timerFired, false); // Timer was cancelled assertEquals(dispatched, false); }); -``` +---- ---- +''''' -### Tea_Vdom - Virtual DOM +==== Tea_Vdom - Virtual DOM Virtual DOM types and constructors for building UIs. -#### API +===== API -```rescript +[source,rescript] +---- // SPDX-License-Identifier: CC-BY-SA-4.0 type node<'msg> @@ -374,53 +422,62 @@ let onMouseLeave: ('msg) => property<'msg> // Mapping let map: (node<'msg>, 'msg => 'mappedMsg) => node<'mappedMsg> -``` +---- -#### Usage Examples +===== Usage Examples -**Simple text:** -```rescript +*Simple text:* + +[source,rescript] +---- Tea_Vdom.text("Hello, World!") -``` +---- + +*Element with attributes:* -**Element with attributes:** -```rescript +[source,rescript] +---- Tea_Vdom.node("div", list{ Tea_Vdom.class_("container"), Tea_Vdom.id("app") }, list{ Tea_Vdom.text("Content") }) -``` +---- -**Interactive button:** -```rescript +*Interactive button:* + +[source,rescript] +---- Tea_Vdom.node("button", list{ Tea_Vdom.onClick(Increment), Tea_Vdom.class_("btn btn-primary") }, list{ Tea_Vdom.text("Click me") }) -``` +---- + +*Form with input:* -**Form with input:** -```rescript +[source,rescript] +---- Tea_Vdom.node("input", list{ Tea_Vdom.placeholder("Enter your name"), Tea_Vdom.value(model.name), Tea_Vdom.onInput(name => UpdateName(name)) }, list{}) -``` +---- ---- +''''' -### Tea_App - Application Runtime +==== Tea_App - Application Runtime Main entry point for running TEA applications. -#### API +===== API -```rescript +[source,rescript] +---- // SPDX-License-Identifier: CC-BY-SA-4.0 type program<'flags, 'model, 'msg> @@ -440,15 +497,16 @@ let standardProgram: { subscriptions: 'model => Tea_Sub.t<'msg>, shutdown: 'model => Tea_Cmd.t<'msg> } => program<'flags, 'model, 'msg> -``` +---- ---- +''''' -## Architecture Guide +=== Architecture Guide -### Complete Application Structure +==== Complete Application Structure -```rescript +[source,rescript] +---- // SPDX-License-Identifier: CC-BY-SA-4.0 // Model.res @@ -519,22 +577,23 @@ let app = Tea_App.simpleProgram({ view: view, subscriptions: subscriptions }) -``` +---- ---- +''''' -## Testing +=== Testing -### Test Coverage +==== Test Coverage -Current test suite (as of v0.1.0-alpha): -- **97 JavaScript tests** via Deno.test (Tea_Cmd, Tea_Sub, Tea_Vdom, Tea_App, Model, Update, View, components) -- **12 Rust tests** via cargo test (Tauri backend commands) -- **109 total tests passing** +Current test suite (as of v0.1.0-alpha): - *97 JavaScript tests* via +Deno.test (Tea_Cmd, Tea_Sub, Tea_Vdom, Tea_App, Model, Update, View, +components) - *12 Rust tests* via cargo test (Tauri backend commands) - +*109 total tests passing* -### Running Tests +==== Running Tests -```bash +[source,bash] +---- # Run all JS tests (97 tests) deno task test @@ -543,13 +602,14 @@ deno task test:watch # Run Rust backend tests (12 tests) cd src-tauri && cargo test -``` +---- -### Test Structure +==== Test Structure Tests use Deno.test with @std/assert: -```javascript +[source,javascript] +---- // SPDX-License-Identifier: CC-BY-SA-4.0 import { assertEquals } from "@std/assert"; import { update } from '../src/Update.res.js'; @@ -561,15 +621,16 @@ Deno.test('Update - increments counter', () => { assertEquals(newModel.count, 1); assertEquals(cmd, "None"); // No command }); -``` +---- ---- +''''' -## Best Practices +=== Best Practices -### 1. Keep Model Simple +==== 1. Keep Model Simple -```rescript +[source,rescript] +---- // ✓ GOOD - Flat, simple structure type model = { users: array, @@ -586,11 +647,12 @@ type model = { } } } -``` +---- -### 2. Use Variants for Messages +==== 2. Use Variants for Messages -```rescript +[source,rescript] +---- // ✓ GOOD - Explicit variants type msg = | UserClicked(string) @@ -602,11 +664,12 @@ type msg = { type_: string, payload: option } -``` +---- -### 3. Extract Complex Commands +==== 3. Extract Complex Commands -```rescript +[source,rescript] +---- // ✓ GOOD - Named, reusable command let loadUserCmd = (userId: string): Tea_Cmd.t => { Tea_Cmd.call(callbacks => { @@ -625,11 +688,12 @@ let loadUserCmd = (userId: string): Tea_Cmd.t => { // In update: | LoadUser(id) => (model, loadUserCmd(id)) -``` +---- -### 4. Always Clean Up Subscriptions +==== 4. Always Clean Up Subscriptions -```rescript +[source,rescript] +---- // ✓ GOOD - Proper cleanup Tea_Sub.registration("websocket", dispatch => { let ws = connect() @@ -640,13 +704,14 @@ Tea_Sub.registration("websocket", dispatch => { ws.onMessage(_ => ()) // Clear handler } }) -``` +---- -### 5. Test Update Function Thoroughly +==== 5. Test Update Function Thoroughly Update is pure - easy to test: -```javascript +[source,javascript] +---- Deno.test('handles error state', () => { const model = { status: 'Loading' }; const msg = { type: 'Error', error: 'Network failed' }; @@ -656,19 +721,20 @@ Deno.test('handles error state', () => { assertEquals(newModel.status, 'Error'); assertEquals(newModel.error, 'Network failed'); }); -``` +---- ---- +''''' -## Examples +=== Examples -### Example 1: Counter +==== Example 1: Counter -See [Architecture Guide](#architecture-guide) above. +See link:#architecture-guide[Architecture Guide] above. -### Example 2: Form with Validation +==== Example 2: Form with Validation -```rescript +[source,rescript] +---- // SPDX-License-Identifier: CC-BY-SA-4.0 type model = { @@ -712,11 +778,12 @@ let update = (model, msg) => { | SubmitResult(Error(err)) => ({...model, errors: list{err}}, Tea_Cmd.none) } } -``` +---- -### Example 3: Real-Time Updates +==== Example 3: Real-Time Updates -```rescript +[source,rescript] +---- // SPDX-License-Identifier: CC-BY-SA-4.0 type model = { @@ -746,19 +813,19 @@ let subscriptions = (model) => { Tea_Sub.none } } -``` +---- ---- +''''' -## References +=== References -- **Original Elm Architecture**: https://guide.elm-lang.org/architecture/ -- **ReScript Documentation**: https://rescript-lang.org/ -- **PanLL Project**: https://github.com/hyperpolymath/panll +* *Original Elm Architecture*: https://guide.elm-lang.org/architecture/ +* *ReScript Documentation*: https://rescript-lang.org/ +* *PanLL Project*: https://github.com/hyperpolymath/panll ---- +''''' -## License +=== License This documentation is licensed under MPL-2.0. diff --git a/docs/guides/TESTING.adoc b/docs/guides/TESTING.adoc new file mode 100644 index 00000000..da408e90 --- /dev/null +++ b/docs/guides/TESTING.adoc @@ -0,0 +1,262 @@ +== Testing Guide + +PanLL has two test suites: Deno tests for the ReScript frontend engines +and Cargo tests for the Rust backend modules. + +=== Running Tests + +==== Frontend (Deno) + +[source,bash] +---- +# Run all tests +deno task test + +# Run all tests (equivalent explicit command) +deno test --no-check --allow-read --allow-env tests/ + +# Watch mode — re-runs on file changes +deno task test:watch + +# With coverage report +deno task test:coverage +---- + +==== Backend (Rust) + +[source,bash] +---- +cd src-tauri && cargo test +---- + +=== Frontend Test Architecture + +Frontend tests import *compiled* `+.res.js+` files from engine modules +and exercise pure functions. No browser or Tauri runtime is needed. + +==== Import Pattern + +[source,javascript] +---- +import { someFunction } from "../src/core/XxxEngine.res.js"; +---- + +Tests import from the compiled JavaScript output of ReScript engines. +The `+--no-check+` flag is required because Deno would otherwise try to +type-check the `+.res.js+` files (which have no type annotations). + +==== What Engines Test + +Engine files (`+src/core/XxxEngine.res+`) contain *pure functions* — +state transitions, data formatting, filtering, validation. They have no +side effects and no Tauri dependencies, making them straightforward to +test. + +Typical test patterns: - Initial state construction - State transition +correctness (applying messages to models) - Filtering and search logic - +Data formatting and serialization - Edge cases (empty arrays, missing +fields, boundary values) + +==== How to Add a New Test File + +[arabic] +. Create `+tests/xxx_engine_test.js+` (snake_case, matching the engine +name) +. Import functions from the compiled engine: ++ +[source,javascript] +---- +import { functionName } from "../src/core/XxxEngine.res.js"; +---- +. Use `+Deno.test()+` with descriptive names: ++ +[source,javascript] +---- +Deno.test("XxxEngine - describes what is being tested", () => { + // Arrange + const input = { /* ... */ }; + // Act + const result = functionName(input); + // Assert + assertEquals(result, expected); +}); +---- +. Run: `+deno task test+` + +==== Permissions + +Tests use two Deno permissions: - `+--allow-read+` — reading compiled +`+.res.js+` files from `+src/+` - `+--allow-env+` — some engines read +environment variables for configuration + +=== Backend Test Architecture + +Rust tests use the standard `+#[cfg(test)]+` module pattern. There are +18 Rust source files with test modules, primarily in the command modules +under `+src-tauri/src//commands.rs+`. + +==== Modules with Rust Tests + +[width="100%",cols="58%,42%",options="header",] +|=== +|Module |File +|main |`+src-tauri/src/main.rs+` +|coprocessor |`+src-tauri/src/coprocessor/commands.rs+` +|k9 |`+src-tauri/src/k9/commands.rs+` +|a2ml |`+src-tauri/src/a2ml/commands.rs+` +|observability |`+src-tauri/src/observability/commands.rs+` +|governance |`+src-tauri/src/governance/commands.rs+` +|umoja |`+src-tauri/src/umoja/commands.rs+` +|release_manager |`+src-tauri/src/release_manager/commands.rs+` +|dlc_workshop |`+src-tauri/src/dlc_workshop/commands.rs+` +|level_architect |`+src-tauri/src/level_architect/commands.rs+` +|multiplayer_monitor |`+src-tauri/src/multiplayer_monitor/commands.rs+` +|network_topology |`+src-tauri/src/network_topology/commands.rs+` +|valence_shell |`+src-tauri/src/valence_shell/commands.rs+` +|vm_inspector |`+src-tauri/src/vm_inspector/commands.rs+` +|game_preview |`+src-tauri/src/game_preview/commands.rs+` +|typell |`+src-tauri/src/typell/commands.rs+` +|boj |`+src-tauri/src/boj/commands.rs+` +|overlay |`+src-tauri/src/overlay/commands.rs+` +|=== + +=== Coverage Matrix + +==== Frontend Test Files (45 files) + +[width="100%",cols="32%,68%",options="header",] +|=== +|Test File |Engine / Module Covered +|`+aerie_engine_test.js+` |AerieEngine + +|`+ai_engine_test.js+` |AiEngine + +|`+anti_crash_test.js+` |AntiCrashModel / validation + +|`+automation_router_engine_test.js+` |AutomationRouterEngine + +|`+boj_engine_test.js+` |BojEngine + +|`+clade_browser_engine_test.js+` |CladeBrowserEngine + +|`+cloudguard_engine_test.js+` |CloudGuardEngine + +|`+connection_manager_test.js+` |Connection management utilities + +|`+contractiles_test.js+` |Contractile validation + +|`+coprocessors_engine_test.js+` |CoprocessorsEngine + +|`+echidna_update_test.js+` |ECHIDNA update integration + +|`+ensaid_config_engine_test.js+` |EnsaidConfigEngine + +|`+event_chain_persistence_test.js+` |Event chain storage + +|`+farm_engine_test.js+` |FarmEngine + +|`+game_preview_engine_test.js+` |GamePreviewEngine + +|`+governance_engine_test.js+` |GovernanceEngine + +|`+keybindings_engine_test.js+` |KeybindingsEngine + +|`+level_architect_engine_test.js+` |LevelArchitectEngine + +|`+minter_engine_test.js+` |MinterEngine + +|`+mylang_engine_test.js+` |MyLangEngine + +|`+network_topology_engine_test.js+` |NetworkTopologyEngine + +|`+orbital_sync_test.js+` |Orbital sync utilities + +|`+panel_registry_test.js+` |PanelRegistry + +|`+panic_attacker_capability_test.js+` |panic-attack capability +detection + +|`+panic_attacker_event_chain_test.js+` |panic-attack event chain +parsing + +|`+panic_attacker_mode_test.js+` |panic-attack mode selection + +|`+plaza_engine_test.js+` |PlazaEngine + +|`+protocol_squisher_engine_test.js+` |ProtocolSquisherEngine + +|`+safedom_bench_test.js+` |SafeDOM benchmarks + +|`+safedom_test.js+` |SafeDOM sanitization + +|`+seam_engine_test.js+` |SeamEngine + +|`+storage_timeline_roundtrip_test.js+` |Storage / timeline persistence + +|`+tea_app_test.js+` |Tea_App lifecycle + +|`+tea_cmd_test.js+` |Tea_Cmd side effects + +|`+tea_render_test.js+` |Tea_Render DOM output + +|`+tea_sub_test.js+` |Tea_Sub subscriptions + +|`+tentacles_engine_test.js+` |TentaclesEngine + +|`+typell_engine_test.js+` |TypeLLEngine + +|`+undo_engine_test.js+` |UndoEngine + +|`+update_integration_test.js+` |Update loop integration + +|`+update_test.js+` |Update function unit tests + +|`+vab_engine_test.js+` |VabEngine + +|`+valence_shell_engine_test.js+` |ValenceShellEngine + +|`+vm_inspector_engine_test.js+` |VmInspectorEngine + +|`+workspace_engine_test.js+` |WorkspaceEngine +|=== + +==== Engines Without Dedicated Test Files + +The following engines in `+src/core/+` do not have matching test files +in `+tests/+`: + +[cols=",",options="header",] +|=== +|Engine |Reason +|BuildDashboardEngine |IDApTIK-specific, tested via integration +|CaptureEngine |File I/O heavy, tested via Rust backend +|DlcWorkshopEngine |IDApTIK-specific, tested via Rust backend +|EditorBridgeEngine |LSP protocol, tested via Rust backend +|FleetEngine |External API dependent +|HypatiaEngine |External API dependent +|InterfacesEngine |Filesystem scanning +|MigrationEngine |CLI integration +|MultiplayerMonitorEngine |WebSocket dependent +|ObservabilityEngine |SARIF/OTel export +|PlaygroundsEngine |NQC proxy dependent +|ProvenanceEngine |Git blame parsing +|ProvisionerEngine |Configuration management +|ReleaseManagerEngine |IDApTIK-specific +|RepoLoaderEngine |Filesystem scanning +|ReposystemEngine |Filesystem scanning +|SecurityEngine |Vault/2FA integration +|StatusBarEngine |UI utility +|VoiceTagEngine |Filesystem I/O +|A2mlEngine |Manifest parsing (tested via Rust) +|K9Engine |Contractile validation (tested via Rust) +|=== + +=== Test Counts + +[cols=",,",options="header",] +|=== +|Suite |Files |Approximate Tests +|Deno (frontend) |45 |~979 +|Cargo (backend) |18 |~164 +|*Total* |*63* |*~1,143* +|=== diff --git a/docs/guides/TESTING.md b/docs/guides/TESTING.md deleted file mode 100644 index 67867def..00000000 --- a/docs/guides/TESTING.md +++ /dev/null @@ -1,203 +0,0 @@ - - - - -# Testing Guide - -PanLL has two test suites: Deno tests for the ReScript frontend engines and -Cargo tests for the Rust backend modules. - -## Running Tests - -### Frontend (Deno) - -```bash -# Run all tests -deno task test - -# Run all tests (equivalent explicit command) -deno test --no-check --allow-read --allow-env tests/ - -# Watch mode — re-runs on file changes -deno task test:watch - -# With coverage report -deno task test:coverage -``` - -### Backend (Rust) - -```bash -cd src-tauri && cargo test -``` - -## Frontend Test Architecture - -Frontend tests import **compiled** `.res.js` files from engine modules and -exercise pure functions. No browser or Tauri runtime is needed. - -### Import Pattern - -```javascript -import { someFunction } from "../src/core/XxxEngine.res.js"; -``` - -Tests import from the compiled JavaScript output of ReScript engines. The -`--no-check` flag is required because Deno would otherwise try to type-check -the `.res.js` files (which have no type annotations). - -### What Engines Test - -Engine files (`src/core/XxxEngine.res`) contain **pure functions** — state -transitions, data formatting, filtering, validation. They have no side effects -and no Tauri dependencies, making them straightforward to test. - -Typical test patterns: -- Initial state construction -- State transition correctness (applying messages to models) -- Filtering and search logic -- Data formatting and serialization -- Edge cases (empty arrays, missing fields, boundary values) - -### How to Add a New Test File - -1. Create `tests/xxx_engine_test.js` (snake_case, matching the engine name) -2. Import functions from the compiled engine: - ```javascript - import { functionName } from "../src/core/XxxEngine.res.js"; - ``` -3. Use `Deno.test()` with descriptive names: - ```javascript - Deno.test("XxxEngine - describes what is being tested", () => { - // Arrange - const input = { /* ... */ }; - // Act - const result = functionName(input); - // Assert - assertEquals(result, expected); - }); - ``` -4. Run: `deno task test` - -### Permissions - -Tests use two Deno permissions: -- `--allow-read` — reading compiled `.res.js` files from `src/` -- `--allow-env` — some engines read environment variables for configuration - -## Backend Test Architecture - -Rust tests use the standard `#[cfg(test)]` module pattern. There are 18 Rust -source files with test modules, primarily in the command modules under -`src-tauri/src//commands.rs`. - -### Modules with Rust Tests - -| Module | File | -|--------|------| -| main | `src-tauri/src/main.rs` | -| coprocessor | `src-tauri/src/coprocessor/commands.rs` | -| k9 | `src-tauri/src/k9/commands.rs` | -| a2ml | `src-tauri/src/a2ml/commands.rs` | -| observability | `src-tauri/src/observability/commands.rs` | -| governance | `src-tauri/src/governance/commands.rs` | -| umoja | `src-tauri/src/umoja/commands.rs` | -| release_manager | `src-tauri/src/release_manager/commands.rs` | -| dlc_workshop | `src-tauri/src/dlc_workshop/commands.rs` | -| level_architect | `src-tauri/src/level_architect/commands.rs` | -| multiplayer_monitor | `src-tauri/src/multiplayer_monitor/commands.rs` | -| network_topology | `src-tauri/src/network_topology/commands.rs` | -| valence_shell | `src-tauri/src/valence_shell/commands.rs` | -| vm_inspector | `src-tauri/src/vm_inspector/commands.rs` | -| game_preview | `src-tauri/src/game_preview/commands.rs` | -| typell | `src-tauri/src/typell/commands.rs` | -| boj | `src-tauri/src/boj/commands.rs` | -| overlay | `src-tauri/src/overlay/commands.rs` | - -## Coverage Matrix - -### Frontend Test Files (45 files) - -| Test File | Engine / Module Covered | -|-----------|------------------------| -| `aerie_engine_test.js` | AerieEngine | -| `ai_engine_test.js` | AiEngine | -| `anti_crash_test.js` | AntiCrashModel / validation | -| `automation_router_engine_test.js` | AutomationRouterEngine | -| `boj_engine_test.js` | BojEngine | -| `clade_browser_engine_test.js` | CladeBrowserEngine | -| `cloudguard_engine_test.js` | CloudGuardEngine | -| `connection_manager_test.js` | Connection management utilities | -| `contractiles_test.js` | Contractile validation | -| `coprocessors_engine_test.js` | CoprocessorsEngine | -| `echidna_update_test.js` | ECHIDNA update integration | -| `ensaid_config_engine_test.js` | EnsaidConfigEngine | -| `event_chain_persistence_test.js` | Event chain storage | -| `farm_engine_test.js` | FarmEngine | -| `game_preview_engine_test.js` | GamePreviewEngine | -| `governance_engine_test.js` | GovernanceEngine | -| `keybindings_engine_test.js` | KeybindingsEngine | -| `level_architect_engine_test.js` | LevelArchitectEngine | -| `minter_engine_test.js` | MinterEngine | -| `mylang_engine_test.js` | MyLangEngine | -| `network_topology_engine_test.js` | NetworkTopologyEngine | -| `orbital_sync_test.js` | Orbital sync utilities | -| `panel_registry_test.js` | PanelRegistry | -| `panic_attacker_capability_test.js` | panic-attack capability detection | -| `panic_attacker_event_chain_test.js` | panic-attack event chain parsing | -| `panic_attacker_mode_test.js` | panic-attack mode selection | -| `plaza_engine_test.js` | PlazaEngine | -| `protocol_squisher_engine_test.js` | ProtocolSquisherEngine | -| `safedom_bench_test.js` | SafeDOM benchmarks | -| `safedom_test.js` | SafeDOM sanitization | -| `seam_engine_test.js` | SeamEngine | -| `storage_timeline_roundtrip_test.js` | Storage / timeline persistence | -| `tea_app_test.js` | Tea_App lifecycle | -| `tea_cmd_test.js` | Tea_Cmd side effects | -| `tea_render_test.js` | Tea_Render DOM output | -| `tea_sub_test.js` | Tea_Sub subscriptions | -| `tentacles_engine_test.js` | TentaclesEngine | -| `typell_engine_test.js` | TypeLLEngine | -| `undo_engine_test.js` | UndoEngine | -| `update_integration_test.js` | Update loop integration | -| `update_test.js` | Update function unit tests | -| `vab_engine_test.js` | VabEngine | -| `valence_shell_engine_test.js` | ValenceShellEngine | -| `vm_inspector_engine_test.js` | VmInspectorEngine | -| `workspace_engine_test.js` | WorkspaceEngine | - -### Engines Without Dedicated Test Files - -The following engines in `src/core/` do not have matching test files in `tests/`: - -| Engine | Reason | -|--------|--------| -| BuildDashboardEngine | IDApTIK-specific, tested via integration | -| CaptureEngine | File I/O heavy, tested via Rust backend | -| DlcWorkshopEngine | IDApTIK-specific, tested via Rust backend | -| EditorBridgeEngine | LSP protocol, tested via Rust backend | -| FleetEngine | External API dependent | -| HypatiaEngine | External API dependent | -| InterfacesEngine | Filesystem scanning | -| MigrationEngine | CLI integration | -| MultiplayerMonitorEngine | WebSocket dependent | -| ObservabilityEngine | SARIF/OTel export | -| PlaygroundsEngine | NQC proxy dependent | -| ProvenanceEngine | Git blame parsing | -| ProvisionerEngine | Configuration management | -| ReleaseManagerEngine | IDApTIK-specific | -| RepoLoaderEngine | Filesystem scanning | -| ReposystemEngine | Filesystem scanning | -| SecurityEngine | Vault/2FA integration | -| StatusBarEngine | UI utility | -| VoiceTagEngine | Filesystem I/O | -| A2mlEngine | Manifest parsing (tested via Rust) | -| K9Engine | Contractile validation (tested via Rust) | - -## Test Counts - -| Suite | Files | Approximate Tests | -|-------|-------|-------------------| -| Deno (frontend) | 45 | ~979 | -| Cargo (backend) | 18 | ~164 | -| **Total** | **63** | **~1,143** | diff --git a/docs/guides/llm-warmup-dev.adoc b/docs/guides/llm-warmup-dev.adoc new file mode 100644 index 00000000..0d9c7c04 --- /dev/null +++ b/docs/guides/llm-warmup-dev.adoc @@ -0,0 +1,209 @@ +== PanLL LLM Warmup (Developer Context) + +=== Identity + +* *Name*: PanLL eNSAID (Neurosymbolic AI Development Environment) +* *License*: MPL-2.0 +* *Author*: Jonathan D.A. Jewell j.d.a.jewell@open.ac.uk +* *Repo*: https://github.com/hyperpolymath/panll + +=== Architecture + +ReScript TEA (The Elm Architecture) frontend with Gossamer (Rust + +WebKitGTK) backend. 106 panels across three panes. Optional Elixir/BEAM +middleware. Zig FFI layer. + +==== TEA Flow + +.... +Model.model → Msg.msg → Update.update → View.view → DOM + ↑ | + └── Tea_Cmd / Tea_Sub ─┘ +.... + +==== Model Dependency Chain + +.... +PaneModel → EchidnaModel → VeriSimModel → GovernanceModel → VabModel → Model +.... + +* `+Model.res+` is a composition root using `+include+` on domain +modules +* GovernanceModel depends on PaneModel for neuralToken only +* VabModel is a leaf module (VabCatalog/VabEngine use it directly) + +=== Source Layout + +.... +src/ + App.res Entry point + Model.res Composition root + Msg.res Message variants + Update.res State transition kernel (~7500 lines) + View.res Root view renderer + Storage.res localStorage persistence + tea/ Custom TEA runtime (18 modules, permanent) + model/ Domain type modules + PaneModel.res Panel-L/N/W state types + EchidnaModel.res ECHIDNA prover types + VeriSimModel.res VeriSimDB types + GovernanceModel.res AntiCrash, Vexometer, Orbital, Contractiles + VabModel.res Verified Assembly Building types + TypeLLModel.res TypeLL type intelligence types + ProtocolSquisherModel.res Protocol compression + MyLangModel.res Personal language panel + core/ Engines + AntiCrash.res Circuit breaker (validates neural tokens) + OrbitalSync.res Cross-panel synchronisation + Contractiles.res Elastic state contracts + TypeLLEngine.res Type inference engine + VabEngine.res Dependency checking + capability computation + VabCatalog.res 108+3 proven-servers component catalog + EventChain.res Event chain + ProtocolSquisherEngine.res + MyLangEngine.res + components/ Panel view components (41+ files) + PanelL.res, PanelN.res, PanelW.res + TypeLL.res, ProtocolSquisher.res, MyLang.res, Vab.res + commands/ Gossamer bridge commands (invoke wrappers) + TypeLLCmd.res, ProtocolSquisherCmd.res, MyLangCmd.res + modules/ Module registry + TypeLLService (cross-panel) + bindings/ FFI bindings (Gossamer) + subscriptions/ Keyboard + polling subscriptions +src-gossamer/ Rust backend (migrated from Tauri) + src/main.rs Backend commands + gossamer.conf.json Configuration +beam/panll_beam/ Elixir/BEAM API layer +ffi/zig/ Zig FFI + build.zig +tests/ Deno.test suite (979 tests, 41 suites) +scripts/ + bundle.ts Deno bundler + mock-echidna.ts Mock ECHIDNA REST server + dev-server.ts Static file server +.... + +=== Build System + +* *deno.json*: Tasks for bundle, css, test, serve, res:build, res:watch +* *rescript.json*: ReScript compiler config (rescript >= 12.0) +* *Cargo.toml*: Rust workspace (src-gossamer, tools/pcc) +* *Justfile*: Orchestration (dev, serve, build, test, mock, etc.) + +==== Build Commands + +[source,bash] +---- +just build # Full production build (ReScript + CSS + Gossamer) +just dev # Dev environment (watchers + Gossamer) +just serve # Browser-only dev (no native window) +just test # 979 tests via deno test +just mock # Mock ECHIDNA on port 9000 +just lint / just fmt # Linting and formatting +just clean # Remove artifacts +---- + +==== Deno Tasks (via deno.json) + +[source,bash] +---- +deno task dev # Gossamer + bundle + serve +deno task build # Production: cargo build --release + bundle + css +deno task bundle # Bundle JS output +deno task css:build # Tailwind CSS minified +deno task res:build # ReScript compile +deno task test # Deno test suite +deno task mock:echidna # Mock ECHIDNA server +---- + +=== Cognitive Governance System + +[width="100%",cols="29%,32%,39%",options="header",] +|=== +|Engine |Purpose |Threshold +|Anti-Crash |Validates all neural tokens against symbolic constraints +|Circuit breaker + +|Vexometer |Operator friction tracking |0.0 (calm) to 1.0 (frustrated) + +|Orbital Sync |Cross-pane synchronisation |Stability, divergence, drift +aura + +|Contractiles |Elastic state contracts |Orbital stability, vexation +ceiling, divergence limit + +|Humidity |Information density |High/Medium/Low +|=== + +=== TypeLL Cross-Panel Service + +TypeLL is NOT just a panel – it is a cross-cutting service. Any panel +can call TypeLLService helpers. All panels MUST degrade gracefully when +TypeLL unavailable. + +Files: TypeLLModel.res, TypeLLEngine.res, TypeLLCmd.res, +TypeLLService.res, TypeLL.res + +=== Backend Services + +[cols=",,,",options="header",] +|=== +|Service |Port |Endpoint |Mock +|ECHIDNA |9000 |/api/v1 |scripts/mock-echidna.ts +|VeriSimDB |8080 |/api/v1 |External +|BoJ server |7700 |/boj/v1 |External +|TypeLL |7800 |- |- +|Dev server |8000 |/public/ |scripts/dev-server.ts +|=== + +=== ReScript Conventions + +* `+list{}+` for vdom children: `+Tea_Html.div(list{}, list{...})+` +* `+Events.onClick+` / `+Events.onInput+` for event handlers +* Pattern match exhaustively on all variant types +* Domain model types in `+src/model/+` – `+Model.res+` only composes via +`+include+` +* Command wrappers in `+src/commands/+` using `+Tea_Cmd.call+` pattern + +=== Critical Invariants + +[arabic] +. SCM files ONLY in `+.machine_readable/+` – never root +. TEA pattern: Model -> Msg -> Update -> View – no MVC, no Redux +. All state in `+Model.model+` – no global mutable state +. Anti-Crash validates ALL neural tokens +. Contractiles evaluate after EVERY state-modifying update +. No TypeScript – ReScript only +. No npm/bun – Deno only (npm only for ReScript compiler via Deno) +. WCAG 2.3 A minimum, AA target +. License: MPL-2.0 on all source files + +=== Related Projects + +[cols=",",options="header",] +|=== +|Project |Role +|ECHIDNA |Theorem prover dispatch +|VeriSimDB |8-modality versioned database +|panic-attack |Security analysis +|BoJ server |Cartridge server, protocol gateway +|TypeLL |Type verification kernel +|contractiles |Elastic contract framework +|gossamer |Desktop shell (Zig + WebKitGTK) +|=== + +=== Testing + +[source,bash] +---- +deno test --no-check --allow-read --allow-env tests/ +---- + +979 tests across 41 suites. Coverage via `+deno task test:coverage+`. + +=== Pre-commit + +[source,bash] +---- +just assail # panic-attack scan +---- diff --git a/docs/guides/llm-warmup-dev.md b/docs/guides/llm-warmup-dev.md deleted file mode 100644 index e0706999..00000000 --- a/docs/guides/llm-warmup-dev.md +++ /dev/null @@ -1,186 +0,0 @@ -# PanLL LLM Warmup (Developer Context) - -## Identity - -- **Name**: PanLL eNSAID (Neurosymbolic AI Development Environment) -- **License**: MPL-2.0 -- **Author**: Jonathan D.A. Jewell -- **Repo**: https://github.com/hyperpolymath/panll - -## Architecture - -ReScript TEA (The Elm Architecture) frontend with Gossamer (Rust + WebKitGTK) backend. -106 panels across three panes. Optional Elixir/BEAM middleware. Zig FFI layer. - -### TEA Flow - -``` -Model.model → Msg.msg → Update.update → View.view → DOM - ↑ | - └── Tea_Cmd / Tea_Sub ─┘ -``` - -### Model Dependency Chain - -``` -PaneModel → EchidnaModel → VeriSimModel → GovernanceModel → VabModel → Model -``` - -- `Model.res` is a composition root using `include` on domain modules -- GovernanceModel depends on PaneModel for neuralToken only -- VabModel is a leaf module (VabCatalog/VabEngine use it directly) - -## Source Layout - -``` -src/ - App.res Entry point - Model.res Composition root - Msg.res Message variants - Update.res State transition kernel (~7500 lines) - View.res Root view renderer - Storage.res localStorage persistence - tea/ Custom TEA runtime (18 modules, permanent) - model/ Domain type modules - PaneModel.res Panel-L/N/W state types - EchidnaModel.res ECHIDNA prover types - VeriSimModel.res VeriSimDB types - GovernanceModel.res AntiCrash, Vexometer, Orbital, Contractiles - VabModel.res Verified Assembly Building types - TypeLLModel.res TypeLL type intelligence types - ProtocolSquisherModel.res Protocol compression - MyLangModel.res Personal language panel - core/ Engines - AntiCrash.res Circuit breaker (validates neural tokens) - OrbitalSync.res Cross-panel synchronisation - Contractiles.res Elastic state contracts - TypeLLEngine.res Type inference engine - VabEngine.res Dependency checking + capability computation - VabCatalog.res 108+3 proven-servers component catalog - EventChain.res Event chain - ProtocolSquisherEngine.res - MyLangEngine.res - components/ Panel view components (41+ files) - PanelL.res, PanelN.res, PanelW.res - TypeLL.res, ProtocolSquisher.res, MyLang.res, Vab.res - commands/ Gossamer bridge commands (invoke wrappers) - TypeLLCmd.res, ProtocolSquisherCmd.res, MyLangCmd.res - modules/ Module registry + TypeLLService (cross-panel) - bindings/ FFI bindings (Gossamer) - subscriptions/ Keyboard + polling subscriptions -src-gossamer/ Rust backend (migrated from Tauri) - src/main.rs Backend commands - gossamer.conf.json Configuration -beam/panll_beam/ Elixir/BEAM API layer -ffi/zig/ Zig FFI - build.zig -tests/ Deno.test suite (979 tests, 41 suites) -scripts/ - bundle.ts Deno bundler - mock-echidna.ts Mock ECHIDNA REST server - dev-server.ts Static file server -``` - -## Build System - -- **deno.json**: Tasks for bundle, css, test, serve, res:build, res:watch -- **rescript.json**: ReScript compiler config (rescript >= 12.0) -- **Cargo.toml**: Rust workspace (src-gossamer, tools/pcc) -- **Justfile**: Orchestration (dev, serve, build, test, mock, etc.) - -### Build Commands - -```bash -just build # Full production build (ReScript + CSS + Gossamer) -just dev # Dev environment (watchers + Gossamer) -just serve # Browser-only dev (no native window) -just test # 979 tests via deno test -just mock # Mock ECHIDNA on port 9000 -just lint / just fmt # Linting and formatting -just clean # Remove artifacts -``` - -### Deno Tasks (via deno.json) - -```bash -deno task dev # Gossamer + bundle + serve -deno task build # Production: cargo build --release + bundle + css -deno task bundle # Bundle JS output -deno task css:build # Tailwind CSS minified -deno task res:build # ReScript compile -deno task test # Deno test suite -deno task mock:echidna # Mock ECHIDNA server -``` - -## Cognitive Governance System - -| Engine | Purpose | Threshold | -|--------|---------|-----------| -| Anti-Crash | Validates all neural tokens against symbolic constraints | Circuit breaker | -| Vexometer | Operator friction tracking | 0.0 (calm) to 1.0 (frustrated) | -| Orbital Sync | Cross-pane synchronisation | Stability, divergence, drift aura | -| Contractiles | Elastic state contracts | Orbital stability, vexation ceiling, divergence limit | -| Humidity | Information density | High/Medium/Low | - -## TypeLL Cross-Panel Service - -TypeLL is NOT just a panel -- it is a cross-cutting service. Any panel can call -TypeLLService helpers. All panels MUST degrade gracefully when TypeLL unavailable. - -Files: TypeLLModel.res, TypeLLEngine.res, TypeLLCmd.res, TypeLLService.res, TypeLL.res - -## Backend Services - -| Service | Port | Endpoint | Mock | -|---------|------|----------|------| -| ECHIDNA | 9000 | /api/v1 | scripts/mock-echidna.ts | -| VeriSimDB | 8080 | /api/v1 | External | -| BoJ server | 7700 | /boj/v1 | External | -| TypeLL | 7800 | - | - | -| Dev server | 8000 | /public/ | scripts/dev-server.ts | - -## ReScript Conventions - -- `list{}` for vdom children: `Tea_Html.div(list{}, list{...})` -- `Events.onClick` / `Events.onInput` for event handlers -- Pattern match exhaustively on all variant types -- Domain model types in `src/model/` -- `Model.res` only composes via `include` -- Command wrappers in `src/commands/` using `Tea_Cmd.call` pattern - -## Critical Invariants - -1. SCM files ONLY in `.machine_readable/` -- never root -2. TEA pattern: Model -> Msg -> Update -> View -- no MVC, no Redux -3. All state in `Model.model` -- no global mutable state -4. Anti-Crash validates ALL neural tokens -5. Contractiles evaluate after EVERY state-modifying update -6. No TypeScript -- ReScript only -7. No npm/bun -- Deno only (npm only for ReScript compiler via Deno) -8. WCAG 2.3 A minimum, AA target -9. License: MPL-2.0 on all source files - -## Related Projects - -| Project | Role | -|---------|------| -| ECHIDNA | Theorem prover dispatch | -| VeriSimDB | 8-modality versioned database | -| panic-attack | Security analysis | -| BoJ server | Cartridge server, protocol gateway | -| TypeLL | Type verification kernel | -| contractiles | Elastic contract framework | -| gossamer | Desktop shell (Zig + WebKitGTK) | - -## Testing - -```bash -deno test --no-check --allow-read --allow-env tests/ -``` - -979 tests across 41 suites. Coverage via `deno task test:coverage`. - -## Pre-commit - -```bash -just assail # panic-attack scan -``` diff --git a/docs/guides/llm-warmup-user.adoc b/docs/guides/llm-warmup-user.adoc new file mode 100644 index 00000000..58ea5bdc --- /dev/null +++ b/docs/guides/llm-warmup-user.adoc @@ -0,0 +1,89 @@ +== PanLL LLM Warmup (User Context) + +=== What This Is + +PanLL (eNSAID) is a three-panel neurosymbolic AI development +environment. License: MPL-2.0. Author: Jonathan D.A. Jewell. + +=== Architecture (30-second version) + +* *ReScript* frontend using *TEA* (The Elm Architecture): Model -> Msg +-> Update -> View +* *Gossamer* backend (Rust + WebKitGTK) — NOT Tauri +* *106 panels* across three panes: Panel-L (Symbolic), Panel-N (Neural), +Panel-W (World) +* Optional *Elixir/BEAM* middleware in `+beam/+` +* *Zig FFI* layer in `+ffi/zig/+` + +=== Three Panels + +[cols=",,",options="header",] +|=== +|Panel |Name |Purpose +|L |Symbolic Mass |Formal constraints, proof editor +|N |Neural Stream |Inference tokens, ECHIDNA advisor +|W |World Barycentre |Task canvas, VeriSimDB, security +|=== + +=== Cognitive Governance + +* *Anti-Crash*: Circuit breaker validating all neural tokens +* *Vexometer*: Operator friction tracking (0.0 calm to 1.0 frustrated) +* *Orbital Sync*: Cross-panel synchronisation +* *Contractiles*: Elastic state contracts + +=== Key Commands + +[source,bash] +---- +just dev # Full dev environment (Gossamer + watchers) +just serve # Browser-only dev +just test # 979 tests, 41 suites +just build # Production build +just mock # Mock ECHIDNA prover (port 9000) +just doctor # Check toolchain +---- + +=== Ports + +[cols=",",options="header",] +|=== +|Port |Service +|8000 |Dev server +|9000 |ECHIDNA theorem prover +|8080 |VeriSimDB (external) +|7700 |BoJ server (external) +|=== + +=== Prerequisites + +Deno >= 2.0, ReScript >= 12.0, Rust/Cargo >= 1.80, Zig >= 0.13, just >= +1.25. Optional: Elixir >= 1.16 (for beam/ middleware). + +=== Key Files + +[cols=",",options="header",] +|=== +|File |Role +|src/Model.res |State composition root +|src/Msg.res |TEA message variants +|src/Update.res |State transition kernel (~7500 lines) +|src/View.res |Root view renderer +|src/tea/ |Custom TEA runtime (18 modules) +|src/core/ |Engines: AntiCrash, OrbitalSync, TypeLLEngine +|src-gossamer/ |Rust backend +|=== + +=== Rules + +* No TypeScript. ReScript only. +* No npm/bun. Deno only (ReScript + Tailwind run via `+npm:+` specifiers +in `+deno.json+`). +* Panels, not panes. +* TEA pattern only. All state in Model.model. +* Anti-Crash validates ALL neural tokens. + +=== Related Projects + +ECHIDNA (prover), VeriSimDB (database), panic-attack (security), BoJ +server (protocol gateway), TypeLL (type verification). diff --git a/docs/guides/llm-warmup-user.md b/docs/guides/llm-warmup-user.md deleted file mode 100644 index 6b955bd0..00000000 --- a/docs/guides/llm-warmup-user.md +++ /dev/null @@ -1,79 +0,0 @@ -# PanLL LLM Warmup (User Context) - -## What This Is - -PanLL (eNSAID) is a three-panel neurosymbolic AI development environment. -License: MPL-2.0. Author: Jonathan D.A. Jewell. - -## Architecture (30-second version) - -- **ReScript** frontend using **TEA** (The Elm Architecture): Model -> Msg -> Update -> View -- **Gossamer** backend (Rust + WebKitGTK) — NOT Tauri -- **106 panels** across three panes: Panel-L (Symbolic), Panel-N (Neural), Panel-W (World) -- Optional **Elixir/BEAM** middleware in `beam/` -- **Zig FFI** layer in `ffi/zig/` - -## Three Panels - -| Panel | Name | Purpose | -|-------|------|---------| -| L | Symbolic Mass | Formal constraints, proof editor | -| N | Neural Stream | Inference tokens, ECHIDNA advisor | -| W | World Barycentre | Task canvas, VeriSimDB, security | - -## Cognitive Governance - -- **Anti-Crash**: Circuit breaker validating all neural tokens -- **Vexometer**: Operator friction tracking (0.0 calm to 1.0 frustrated) -- **Orbital Sync**: Cross-panel synchronisation -- **Contractiles**: Elastic state contracts - -## Key Commands - -```bash -just dev # Full dev environment (Gossamer + watchers) -just serve # Browser-only dev -just test # 979 tests, 41 suites -just build # Production build -just mock # Mock ECHIDNA prover (port 9000) -just doctor # Check toolchain -``` - -## Ports - -| Port | Service | -|------|---------| -| 8000 | Dev server | -| 9000 | ECHIDNA theorem prover | -| 8080 | VeriSimDB (external) | -| 7700 | BoJ server (external) | - -## Prerequisites - -Deno >= 2.0, ReScript >= 12.0, Rust/Cargo >= 1.80, Zig >= 0.13, just >= 1.25. -Optional: Elixir >= 1.16 (for beam/ middleware). - -## Key Files - -| File | Role | -|------|------| -| src/Model.res | State composition root | -| src/Msg.res | TEA message variants | -| src/Update.res | State transition kernel (~7500 lines) | -| src/View.res | Root view renderer | -| src/tea/ | Custom TEA runtime (18 modules) | -| src/core/ | Engines: AntiCrash, OrbitalSync, TypeLLEngine | -| src-gossamer/ | Rust backend | - -## Rules - -- No TypeScript. ReScript only. -- No npm/bun. Deno only (ReScript + Tailwind run via `npm:` specifiers in `deno.json`). -- Panels, not panes. -- TEA pattern only. All state in Model.model. -- Anti-Crash validates ALL neural tokens. - -## Related Projects - -ECHIDNA (prover), VeriSimDB (database), panic-attack (security), -BoJ server (protocol gateway), TypeLL (type verification). diff --git a/docs/identity-user-guide.adoc b/docs/identity-user-guide.adoc new file mode 100644 index 00000000..0884de65 --- /dev/null +++ b/docs/identity-user-guide.adoc @@ -0,0 +1,182 @@ +== PanLL Identity Management User Guide + +=== Overview + +PanLL’s Identity Management system allows you to capture, save, load, +and share your complete workbench configuration. This includes panel +states, settings, and service URLs - everything needed to restore your +exact working environment. + +=== Key Concepts + +==== Identity Snapshots + +An *Identity Snapshot* is a complete save of your PanLL configuration at +a specific point in time. Each snapshot includes: + +* *Panel State*: Positions and sizes of all panels (PaneL, PaneN, PaneW, +etc.) +* *Settings*: All user configuration settings +* *Service URLs*: Registered service endpoints +* *Metadata*: Unique ID, name, and creation timestamp + +==== Storage Hierarchy + +[arabic] +. *Primary Storage*: VeriSimDB (persistent, network-accessible) +. *Fallback Storage*: Local filesystem (`+~/.panll/identities/+`) + +=== Using Identity Management + +==== Creating a Snapshot + +[arabic] +. *Via UI*: Click the "`Save Identity`" button in the settings panel +. *Via Command*: Use the `+identity_save+` command with a name for your +snapshot + +[source,javascript] +---- +// Example: Save current state as "Project Alpha Setup" +await invoke("identity_save", { + name: "Project Alpha Setup", + panll_state: JSON.stringify(storage.serialize()), + settings: JSON.stringify(await settings_get()), + service_urls: JSON.stringify(await service_registry_get()) +}); +---- + +==== Loading a Snapshot + +[arabic] +. *Via UI*: Select a snapshot from the identity manager panel and click +"`Load`" +. *Via Command*: Use the `+identity_load+` command with a snapshot ID + +[source,javascript] +---- +// Example: Load snapshot by ID +await invoke("identity_load", { id: "snapshot-id-here" }); +---- + +==== Managing Snapshots + +===== Listing All Snapshots + +[source,javascript] +---- +const snapshots = await invoke("identity_list"); +console.log("Available snapshots:", snapshots); +---- + +===== Deleting a Snapshot + +[source,javascript] +---- +await invoke("identity_delete", { id: "snapshot-id-to-delete" }); +---- + +=== Team Collaboration + +==== Broadcasting Your Identity + +Share your current configuration with team members: + +[source,javascript] +---- +// First save your current state +const snapshot = await invoke("identity_save", { + name: "Team Setup", + panll_state: JSON.stringify(storage.serialize()), + settings: JSON.stringify(await settings_get()), + service_urls: JSON.stringify(await service_registry_get()) +}); + +// Then broadcast to team +await invoke("team_broadcast_state", { + snapshot_json: snapshot +}); +---- + +==== Receiving Team Broadcasts + +When a team member broadcasts their identity: 1. You’ll receive a +notification in the system tray 2. Review the snapshot details 3. Choose +to apply or discard the changes + +=== Best Practices + +==== Naming Conventions + +Use descriptive names for snapshots: - *Good*: "`Project X - UI Research +Phase`" - *Good*: "`Production Setup - 2024-05-15`" - *Avoid*: +"`Snapshot 1`", "`Backup`" + +==== Regular Backups + +* Save snapshots before major configuration changes +* Create snapshots at the end of work sessions +* Keep 3-5 recent snapshots for easy rollback + +==== Team Workflows + +* Broadcast team-wide configurations at project start +* Share specialized setups for specific tasks +* Use snapshots to onboard new team members quickly + +=== Advanced Usage + +==== Programmatic Access + +Access identity functions directly from your PanLL scripts: + +[source,javascript] +---- +// Get all snapshots and process them +const allSnapshots = await invoke("identity_list"); +const detailedInfo = await Promise.all( + allSnapshots.map(async (snapshot) => { + const data = await invoke("identity_load", { id: snapshot.id }); + return { ...snapshot, data }; + }) +); +---- + +==== VeriSimDB Integration + +Identity snapshots are stored in VeriSimDB by default. You can: - Access +snapshots from any machine with VeriSimDB access - Share snapshots +across your organization - Use VeriSimDB’s query capabilities to find +specific configurations + +=== Troubleshooting + +==== Common Issues + +*Issue*: Snapshots not appearing in list - *Solution*: Check VeriSimDB +connection and fallback to local storage + +*Issue*: Loading snapshot fails - *Solution*: Verify snapshot ID and +check for corruption + +*Issue*: Team broadcast not received - *Solution*: Check Burble service +status and network connectivity + +==== VeriSimDB Fallback + +If VeriSimDB is unavailable, PanLL automatically falls back to local +filesystem storage. You can: - Continue working normally - Snapshots +will sync to VeriSimDB when connection is restored - Check system tray +for service status indicators + +=== Security Considerations + +* Identity snapshots may contain sensitive configuration data +* Be cautious when broadcasting to teams +* Review snapshot contents before sharing +* Use VeriSimDB access controls to limit who can view your snapshots + +=== API Reference + +For complete API documentation, see the link:api-reference.md[VeriSimDB +Integration API Reference]. diff --git a/docs/identity-user-guide.md b/docs/identity-user-guide.md deleted file mode 100644 index f4668943..00000000 --- a/docs/identity-user-guide.md +++ /dev/null @@ -1,167 +0,0 @@ -# PanLL Identity Management User Guide - -## Overview - -PanLL's Identity Management system allows you to capture, save, load, and share your complete workbench configuration. This includes panel states, settings, and service URLs - everything needed to restore your exact working environment. - -## Key Concepts - -### Identity Snapshots - -An **Identity Snapshot** is a complete save of your PanLL configuration at a specific point in time. Each snapshot includes: - -- **Panel State**: Positions and sizes of all panels (PaneL, PaneN, PaneW, etc.) -- **Settings**: All user configuration settings -- **Service URLs**: Registered service endpoints -- **Metadata**: Unique ID, name, and creation timestamp - -### Storage Hierarchy - -1. **Primary Storage**: VeriSimDB (persistent, network-accessible) -2. **Fallback Storage**: Local filesystem (`~/.panll/identities/`) - -## Using Identity Management - -### Creating a Snapshot - -1. **Via UI**: Click the "Save Identity" button in the settings panel -2. **Via Command**: Use the `identity_save` command with a name for your snapshot - -```javascript -// Example: Save current state as "Project Alpha Setup" -await invoke("identity_save", { - name: "Project Alpha Setup", - panll_state: JSON.stringify(storage.serialize()), - settings: JSON.stringify(await settings_get()), - service_urls: JSON.stringify(await service_registry_get()) -}); -``` - -### Loading a Snapshot - -1. **Via UI**: Select a snapshot from the identity manager panel and click "Load" -2. **Via Command**: Use the `identity_load` command with a snapshot ID - -```javascript -// Example: Load snapshot by ID -await invoke("identity_load", { id: "snapshot-id-here" }); -``` - -### Managing Snapshots - -#### Listing All Snapshots - -```javascript -const snapshots = await invoke("identity_list"); -console.log("Available snapshots:", snapshots); -``` - -#### Deleting a Snapshot - -```javascript -await invoke("identity_delete", { id: "snapshot-id-to-delete" }); -``` - -## Team Collaboration - -### Broadcasting Your Identity - -Share your current configuration with team members: - -```javascript -// First save your current state -const snapshot = await invoke("identity_save", { - name: "Team Setup", - panll_state: JSON.stringify(storage.serialize()), - settings: JSON.stringify(await settings_get()), - service_urls: JSON.stringify(await service_registry_get()) -}); - -// Then broadcast to team -await invoke("team_broadcast_state", { - snapshot_json: snapshot -}); -``` - -### Receiving Team Broadcasts - -When a team member broadcasts their identity: -1. You'll receive a notification in the system tray -2. Review the snapshot details -3. Choose to apply or discard the changes - -## Best Practices - -### Naming Conventions - -Use descriptive names for snapshots: -- **Good**: "Project X - UI Research Phase" -- **Good**: "Production Setup - 2024-05-15" -- **Avoid**: "Snapshot 1", "Backup" - -### Regular Backups - -- Save snapshots before major configuration changes -- Create snapshots at the end of work sessions -- Keep 3-5 recent snapshots for easy rollback - -### Team Workflows - -- Broadcast team-wide configurations at project start -- Share specialized setups for specific tasks -- Use snapshots to onboard new team members quickly - -## Advanced Usage - -### Programmatic Access - -Access identity functions directly from your PanLL scripts: - -```javascript -// Get all snapshots and process them -const allSnapshots = await invoke("identity_list"); -const detailedInfo = await Promise.all( - allSnapshots.map(async (snapshot) => { - const data = await invoke("identity_load", { id: snapshot.id }); - return { ...snapshot, data }; - }) -); -``` - -### VeriSimDB Integration - -Identity snapshots are stored in VeriSimDB by default. You can: -- Access snapshots from any machine with VeriSimDB access -- Share snapshots across your organization -- Use VeriSimDB's query capabilities to find specific configurations - -## Troubleshooting - -### Common Issues - -**Issue**: Snapshots not appearing in list -- **Solution**: Check VeriSimDB connection and fallback to local storage - -**Issue**: Loading snapshot fails -- **Solution**: Verify snapshot ID and check for corruption - -**Issue**: Team broadcast not received -- **Solution**: Check Burble service status and network connectivity - -### VeriSimDB Fallback - -If VeriSimDB is unavailable, PanLL automatically falls back to local filesystem storage. You can: -- Continue working normally -- Snapshots will sync to VeriSimDB when connection is restored -- Check system tray for service status indicators - -## Security Considerations - -- Identity snapshots may contain sensitive configuration data -- Be cautious when broadcasting to teams -- Review snapshot contents before sharing -- Use VeriSimDB access controls to limit who can view your snapshots - -## API Reference - -For complete API documentation, see the [VeriSimDB Integration API Reference](api-reference.md). \ No newline at end of file diff --git a/docs/migration-guide.md b/docs/migration-guide.adoc similarity index 73% rename from docs/migration-guide.md rename to docs/migration-guide.adoc index 917cccf0..e37a2cfd 100644 --- a/docs/migration-guide.md +++ b/docs/migration-guide.adoc @@ -1,44 +1,54 @@ -# PanLL Migration Guide: v0.1.x to v0.2.0 - -## Overview - -This guide provides step-by-step instructions for migrating from PanLL v0.1.x (Tauri-based) to v0.2.0 (Gossamer-based). The migration includes architectural changes, new features, and breaking changes that require careful planning. - -## Table of Contents - -1. [What's New in v0.2.0](#whats-new-in-v020) -2. [Breaking Changes](#breaking-changes) -3. [Pre-Migration Checklist](#pre-migration-checklist) -4. [Migration Steps](#migration-steps) -5. [Post-Migration Tasks](#post-migration-tasks) -6. [Troubleshooting](#troubleshooting) -7. [Rollback Procedure](#rollback-procedure) -8. [Frequently Asked Questions](#frequently-asked-questions) - -## What's New in v0.2.0 - -### Major Changes - -| Feature | v0.1.x | v0.2.0 | Impact | -|---------|-------|-------|--------| -| **Backend** | Tauri 2.0 | Gossamer | 🔴 Breaking | -| **IPC System** | Tauri IPC | Gossamer FFI | 🔴 Breaking | -| **Storage** | Local only | VeriSimDB + Local | ✅ Additive | -| **Team Features** | None | Burble integration | ✅ New | -| **System Tray** | Basic | Full featured | ✅ Enhanced | -| **Identity Management** | None | Full implementation | ✅ New | - -### New Features - -1. **VeriSimDB Integration**: Primary storage backend with filesystem fallback -2. **Identity Snapshots**: Capture and restore complete workbench configurations -3. **Team Broadcasting**: Share configurations with team members via Burble -4. **Enhanced System Tray**: Service toggling and status monitoring -5. **Improved Performance**: Optimized Rust backend with caching - -### Architecture Changes - -```mermaid +== PanLL Migration Guide: v0.1.x to v0.2.0 + +=== Overview + +This guide provides step-by-step instructions for migrating from PanLL +v0.1.x (Tauri-based) to v0.2.0 (Gossamer-based). The migration includes +architectural changes, new features, and breaking changes that require +careful planning. + +=== Table of Contents + +[arabic] +. link:#whats-new-in-v020[What’s New in v0.2.0] +. link:#breaking-changes[Breaking Changes] +. link:#pre-migration-checklist[Pre-Migration Checklist] +. link:#migration-steps[Migration Steps] +. link:#post-migration-tasks[Post-Migration Tasks] +. link:#troubleshooting[Troubleshooting] +. link:#rollback-procedure[Rollback Procedure] +. link:#frequently-asked-questions[Frequently Asked Questions] + +=== What’s New in v0.2.0 + +==== Major Changes + +[cols=",,,",options="header",] +|=== +|Feature |v0.1.x |v0.2.0 |Impact +|*Backend* |Tauri 2.0 |Gossamer |🔴 Breaking +|*IPC System* |Tauri IPC |Gossamer FFI |🔴 Breaking +|*Storage* |Local only |VeriSimDB + Local |✅ Additive +|*Team Features* |None |Burble integration |✅ New +|*System Tray* |Basic |Full featured |✅ Enhanced +|*Identity Management* |None |Full implementation |✅ New +|=== + +==== New Features + +[arabic] +. *VeriSimDB Integration*: Primary storage backend with filesystem +fallback +. *Identity Snapshots*: Capture and restore complete workbench +configurations +. *Team Broadcasting*: Share configurations with team members via Burble +. *Enhanced System Tray*: Service toggling and status monitoring +. *Improved Performance*: Optimized Rust backend with caching + +==== Architecture Changes + +[source,mermaid] +---- graph LR A[v0.1.x Tauri] -->|Migrates to| B[v0.2.0 Gossamer] @@ -53,57 +63,62 @@ graph LR B2 -->|HTTP| B4[Burble] B2 -->|FS| B5[Local Storage] end -``` +---- -## Breaking Changes +=== Breaking Changes -### Backend Architecture +==== Backend Architecture -**Impact**: High +*Impact*: High -- **Tauri IPC → Gossamer FFI**: All frontend-backend communication uses new FFI layer -- **Command Structure**: Some commands renamed or restructured -- **Configuration Format**: New TOML-based configuration system +* *Tauri IPC → Gossamer FFI*: All frontend-backend communication uses +new FFI layer +* *Command Structure*: Some commands renamed or restructured +* *Configuration Format*: New TOML-based configuration system -### Frontend Framework +==== Frontend Framework -**Impact**: Medium +*Impact*: Medium -- **Svelte → ReScript**: Frontend rewritten in ReScript (compatible with ReasonML/OCaml) -- **Component Structure**: New component hierarchy and state management -- **Styling**: Updated CSS structure and theming system +* *Svelte → ReScript*: Frontend rewritten in ReScript (compatible with +ReasonML/OCaml) +* *Component Structure*: New component hierarchy and state management +* *Styling*: Updated CSS structure and theming system -### Storage System +==== Storage System -**Impact**: Low (backward compatible) +*Impact*: Low (backward compatible) -- **Local Storage Path**: Changed from `~/.panll/v1/` to `~/.panll/` -- **Snapshot Format**: Enhanced with additional metadata fields -- **Configuration Files**: New structure and location +* *Local Storage Path*: Changed from `+~/.panll/v1/+` to `+~/.panll/+` +* *Snapshot Format*: Enhanced with additional metadata fields +* *Configuration Files*: New structure and location -### Command Changes +==== Command Changes -| v0.1.x Command | v0.2.0 Command | Status | -|----------------|-----------------|--------| -| `save_config` | `identity_save` | ✅ Compatible | -| `load_config` | `identity_load` | ✅ Compatible | -| `tauri_command` | `gossamer_command` | 🔴 Renamed | -| `get_version` | `panll_version` | ✅ Compatible | -| `system_info` | `system_status` | 🟡 Enhanced | +[cols=",,",options="header",] +|=== +|v0.1.x Command |v0.2.0 Command |Status +|`+save_config+` |`+identity_save+` |✅ Compatible +|`+load_config+` |`+identity_load+` |✅ Compatible +|`+tauri_command+` |`+gossamer_command+` |🔴 Renamed +|`+get_version+` |`+panll_version+` |✅ Compatible +|`+system_info+` |`+system_status+` |🟡 Enhanced +|=== -## Pre-Migration Checklist +=== Pre-Migration Checklist -### System Requirements +==== System Requirements -- **Operating System**: Linux (Ubuntu 22.04+, Fedora 38+, Debian 11+) -- **CPU**: 2+ cores (4+ recommended) -- **RAM**: 4GB+ (8GB+ recommended) -- **Disk Space**: 1GB+ free space -- **Dependencies**: Rust, Deno, GTK3, WebKitGTK +* *Operating System*: Linux (Ubuntu 22.04+, Fedora 38+, Debian 11+) +* *CPU*: 2+ cores (4+ recommended) +* *RAM*: 4GB+ (8GB+ recommended) +* *Disk Space*: 1GB+ free space +* *Dependencies*: Rust, Deno, GTK3, WebKitGTK -### Backup Requirements +==== Backup Requirements -```bash +[source,bash] +---- # Create comprehensive backup mkdir -p /var/backups/panll-migration-$(date +%Y%m%d) @@ -118,11 +133,12 @@ tar -czf /var/backups/panll-migration-$(date +%Y%m%d)/snapshots.tar.gz ~/.panll/ # Verify backup ls -lh /var/backups/panll-migration-$(date +%Y%m%d)/ -``` +---- -### Compatibility Check +==== Compatibility Check -```bash +[source,bash] +---- # Check current version panll --version @@ -133,11 +149,12 @@ deno --version # Check GTK/WebKit pkg-config --modversion gtk+-3.0 pkg-config --modversion webkit2gtk-4.0 -``` +---- -### Service Status +==== Service Status -```bash +[source,bash] +---- # Check running services systemctl status panll-tauri systemctl status panll-verisimdb # If installed @@ -145,13 +162,14 @@ systemctl status panll-burble # If installed # Check port usage ss -tulnp | grep -E '8000|8080|6473' -``` +---- -## Migration Steps +=== Migration Steps -### Step 1: Install Prerequisites +==== Step 1: Install Prerequisites -```bash +[source,bash] +---- # Update system sudo apt update && sudo apt upgrade -y @@ -174,11 +192,12 @@ source $HOME/.cargo/env curl -fsSL https://deno.land/x/install/install.sh | sh export DENO_INSTALL="/home/$USER/.deno" export PATH="$DENO_INSTALL/bin:$PATH" -``` +---- -### Step 2: Backup Existing Installation +==== Step 2: Backup Existing Installation -```bash +[source,bash] +---- # Create migration backup script cat > /usr/local/bin/panll-migration-backup.sh << 'EOF' #!/bin/bash @@ -237,11 +256,12 @@ chmod +x /usr/local/bin/panll-migration-backup.sh # Run backup sudo /usr/local/bin/panll-migration-backup.sh -``` +---- -### Step 3: Stop Existing Services +==== Step 3: Stop Existing Services -```bash +[source,bash] +---- # Stop PanLL v0.1.x services echo "Stopping PanLL v0.1.x services..." sudo systemctl stop panll-tauri 2>/dev/null || true @@ -254,11 +274,12 @@ sudo systemctl disable panll 2>/dev/null || true # Verify services stopped systemctl status panll-tauri 2>&1 | grep -q "inactive" && echo "✅ Tauri service stopped" systemctl status panll 2>&1 | grep -q "inactive" && echo "✅ PanLL service stopped" -``` +---- -### Step 4: Install v0.2.0 +==== Step 4: Install v0.2.0 -```bash +[source,bash] +---- # Download v0.2.0 echo "Downloading PanLL v0.2.0..." wget https://github.com/hyperpolymath/panll/releases/download/v0.2.0/panll-v0.2.0-linux-x86_64.tar.gz @@ -275,11 +296,12 @@ sudo ./install.sh # Verify installation panll --version echo "✅ PanLL v0.2.0 installed" -``` +---- -### Step 5: Migrate Configuration +==== Step 5: Migrate Configuration -```bash +[source,bash] +---- # Create migration script cat > /usr/local/bin/panll-migrate-config.sh << 'EOF' #!/bin/bash @@ -396,11 +418,12 @@ chmod +x /usr/local/bin/panll-migrate-config.sh # Run migration sudo /usr/local/bin/panll-migrate-config.sh -``` +---- -### Step 6: Install Dependencies +==== Step 6: Install Dependencies -```bash +[source,bash] +---- # Install VeriSimDB (required for v0.2.0) echo "Installing VeriSimDB..." git clone https://github.com/hyperpolymath/verisimdb.git @@ -455,11 +478,12 @@ sudo systemctl enable burble sudo systemctl start burble echo "✅ Dependencies installed" -``` +---- -### Step 7: Configure Systemd Service +==== Step 7: Configure Systemd Service -```bash +[source,bash] +---- # Create new systemd service cat > /etc/systemd/system/panll.service << 'EOF' [Unit] @@ -496,11 +520,12 @@ sudo systemctl start panll # Verify service systemctl status panll echo "✅ PanLL v0.2.0 service configured" -``` +---- -### Step 8: Migrate Data +==== Step 8: Migrate Data -```bash +[source,bash] +---- # Create data migration script cat > /usr/local/bin/panll-migrate-data.sh << 'EOF' #!/bin/bash @@ -582,11 +607,12 @@ chmod +x /usr/local/bin/panll-migrate-data.sh # Run data migration sudo /usr/local/bin/panll-migrate-data.sh -``` +---- -### Step 9: Test Migration +==== Step 9: Test Migration -```bash +[source,bash] +---- # Test PanLL service echo "Testing PanLL v0.2.0..." @@ -621,11 +647,12 @@ echo "Test snapshot created: $test_snapshot" curl -s http://localhost:8080/api/v1/identity_list | jq . echo "✅ Migration tests completed" -``` +---- -### Step 10: Cleanup +==== Step 10: Cleanup -```bash +[source,bash] +---- # Remove old services sudo rm -f /etc/systemd/system/panll-tauri.service sudo systemctl daemon-reload @@ -638,13 +665,14 @@ rm -f panll-v0.2.0-linux-x86_64.tar.gz rm -rf panll-v0.2.0-linux-x86_64 echo "✅ Cleanup completed" -``` +---- -## Post-Migration Tasks +=== Post-Migration Tasks -### Verify Migration +==== Verify Migration -```bash +[source,bash] +---- # Comprehensive verification script cat > /usr/local/bin/panll-verify-migration.sh << 'EOF' #!/bin/bash @@ -701,11 +729,12 @@ chmod +x /usr/local/bin/panll-verify-migration.sh # Run verification sudo /usr/local/bin/panll-verify-migration.sh -``` +---- -### Update Documentation +==== Update Documentation -```bash +[source,bash] +---- # Update README with v0.2.0 information if [ -f "README.md" ]; then sed -i 's/v0.1.x/v0.2.0/g' README.md @@ -747,11 +776,12 @@ Backup location: $(ls -td /var/backups/panll-migration-* | head -1) EOF echo "✅ Migration notes created" -``` +---- -### User Communication +==== User Communication -```bash +[source,bash] +---- # Create user notification cat > /etc/motd.panll << 'EOF' ================================================================= @@ -778,18 +808,20 @@ EOF sudo cp /etc/motd.panll /etc/motd echo "✅ User notification created" -``` +---- + +=== Troubleshooting -## Troubleshooting +==== Common Issues -### Common Issues +===== Service Fails to Start -#### Service Fails to Start +*Symptoms*: `+systemctl status panll+` shows failed state -**Symptoms**: `systemctl status panll` shows failed state +*Solutions*: -**Solutions**: -```bash +[source,bash] +---- # Check logs journalctl -u panll -n 50 @@ -801,14 +833,16 @@ panll --config /etc/panll/panll.config.toml --dev # Check port conflicts ss -tulnp | grep 8080 -``` +---- -#### VeriSimDB Connection Issues +===== VeriSimDB Connection Issues -**Symptoms**: "VeriSimDB unavailable" errors +*Symptoms*: "`VeriSimDB unavailable`" errors -**Solutions**: -```bash +*Solutions*: + +[source,bash] +---- # Check VeriSimDB status systemctl status verisimdb @@ -821,14 +855,16 @@ cat /etc/panll/services.toml # Test with fallback export VERISIMDB_URL="" panll --config /etc/panll/panll.config.toml -``` +---- + +===== Permission Errors -#### Permission Errors +*Symptoms*: "`Permission denied`" errors -**Symptoms**: "Permission denied" errors +*Solutions*: -**Solutions**: -```bash +[source,bash] +---- # Check directory permissions ls -la /etc/panll /var/panll @@ -839,14 +875,16 @@ sudo chmod 750 /etc/panll /var/panll # Check SELinux getenforce sudo setenforce 0 # Test with SELinux disabled -``` +---- + +===== Data Migration Issues -#### Data Migration Issues +*Symptoms*: Missing snapshots or corrupted data -**Symptoms**: Missing snapshots or corrupted data +*Solutions*: -**Solutions**: -```bash +[source,bash] +---- # Check backup BACKUP_DIR=$(ls -td /var/backups/panll-migration-* | head -1) ls -la "$BACKUP_DIR" @@ -856,11 +894,12 @@ sudo /usr/local/bin/panll-migrate-data.sh # Verify data integrity sudo /usr/local/bin/panll-verify-migration.sh -``` +---- -### Debugging Commands +==== Debugging Commands -```bash +[source,bash] +---- # Enable debug logging sudo sed -i 's/PANLL_LOG_LEVEL=info/PANLL_LOG_LEVEL=debug/' /etc/systemd/system/panll.service sudo systemctl restart panll @@ -877,13 +916,14 @@ curl -v http://localhost:6473/api/v1/status ping localhost nc -zv localhost 8080 nc -zv localhost 6473 -``` +---- -## Rollback Procedure +=== Rollback Procedure -### Emergency Rollback +==== Emergency Rollback -```bash +[source,bash] +---- # Stop new services sudo systemctl stop panll sudo systemctl stop verisimdb @@ -918,11 +958,12 @@ panll-tauri --version systemctl status panll-tauri echo "⚠️ Rollback completed - running v0.1.x" -``` +---- -### Partial Rollback +==== Partial Rollback -```bash +[source,bash] +---- # Rollback only configuration BACKUP_DIR=$(ls -td /var/backups/panll-migration-* | head -1) sudo cp -r "$BACKUP_DIR/etc/panll" /etc/ @@ -937,78 +978,69 @@ sudo systemctl restart panll SNAPSHOT_ID="your-snapshot-id" sudo cp "$BACKUP_DIR/var/panll/identities/$SNAPSHOT_ID.json" /var/panll/identities/ sudo chown panll:panll /var/panll/identities/$SNAPSHOT_ID.json -``` +---- -## Frequently Asked Questions +=== Frequently Asked Questions -### Why migrate from Tauri to Gossamer? +==== Why migrate from Tauri to Gossamer? -Gossamer provides: -- Better performance and lower memory usage -- More control over the webview implementation -- Simplified FFI interface -- Better integration with Rust ecosystem -- Reduced binary size +Gossamer provides: - Better performance and lower memory usage - More +control over the webview implementation - Simplified FFI interface - +Better integration with Rust ecosystem - Reduced binary size -### What happens to my existing snapshots? +==== What happens to my existing snapshots? -Existing snapshots are automatically migrated: -1. Copied to new location (`/var/panll/identities/`) -2. Format enhanced with additional metadata -3. Imported into VeriSimDB for primary storage -4. Local copies maintained as fallback +Existing snapshots are automatically migrated: 1. Copied to new location +(`+/var/panll/identities/+`) 2. Format enhanced with additional metadata +3. Imported into VeriSimDB for primary storage 4. Local copies +maintained as fallback -### Do I need to reinstall all plugins? +==== Do I need to reinstall all plugins? -Yes. The plugin system has been completely redesigned in v0.2.0. You'll need to: -1. Check plugin compatibility -2. Reinstall plugins using new API -3. Reconfigure plugin settings +Yes. The plugin system has been completely redesigned in v0.2.0. You’ll +need to: 1. Check plugin compatibility 2. Reinstall plugins using new +API 3. Reconfigure plugin settings -### How do I access the new features? +==== How do I access the new features? -New features are accessible through: -- **System Tray**: Right-click icon for menu -- **Command Palette**: Ctrl+K for identity commands -- **API**: New endpoints for programmatic access -- **CLI**: Additional command-line options +New features are accessible through: - *System Tray*: Right-click icon +for menu - *Command Palette*: Ctrl+K for identity commands - *API*: New +endpoints for programmatic access - *CLI*: Additional command-line +options -### What if I encounter issues after migration? +==== What if I encounter issues after migration? -1. Check the troubleshooting section above -2. Review migration logs in `/var/log/panll/` -3. Consult the backup in `/var/backups/panll-migration-*` -4. Contact support with detailed error information +[arabic] +. Check the troubleshooting section above +. Review migration logs in `+/var/log/panll/+` +. Consult the backup in `+/var/backups/panll-migration-*+` +. Contact support with detailed error information -### Can I run both versions side by side? +==== Can I run both versions side by side? -Not recommended, but possible: -1. Install v0.2.0 in different location -2. Use different ports -3. Run with `--config` flag to specify configuration -4. Be aware of potential conflicts +Not recommended, but possible: 1. Install v0.2.0 in different location +2. Use different ports 3. Run with `+--config+` flag to specify +configuration 4. Be aware of potential conflicts -### How long does migration take? +==== How long does migration take? -Migration time depends on: -- Number of snapshots: ~10ms per snapshot -- Data size: ~1MB per second -- System performance: CPU and disk speed +Migration time depends on: - Number of snapshots: ~10ms per snapshot - +Data size: ~1MB per second - System performance: CPU and disk speed Typical migration: 1-5 minutes for average installation -### What's the rollback window? +==== What’s the rollback window? -Backups are kept for 30 days by default. You can: -- Rollback anytime within this period -- Extend backup retention by modifying cleanup scripts -- Create manual backups for longer retention +Backups are kept for 30 days by default. You can: - Rollback anytime +within this period - Extend backup retention by modifying cleanup +scripts - Create manual backups for longer retention -## Support +=== Support -### Getting Help +==== Getting Help -```bash +[source,bash] +---- # Check documentation panll --help man panll @@ -1022,20 +1054,21 @@ panll --version # Test connectivity curl http://localhost:8080/health -``` +---- -### Contact Support +==== Contact Support -- **Email**: support@hyperpolymath.dev -- **GitHub Issues**: https://github.com/hyperpolymath/panll/issues -- **Discussions**: https://github.com/hyperpolymath/panll/discussions -- **Documentation**: https://panll.hyperpolymath.dev/docs +* *Email*: support@hyperpolymath.dev +* *GitHub Issues*: https://github.com/hyperpolymath/panll/issues +* *Discussions*: https://github.com/hyperpolymath/panll/discussions +* *Documentation*: https://panll.hyperpolymath.dev/docs -### Providing Debug Information +==== Providing Debug Information When reporting issues, include: -```bash +[source,bash] +---- # System information uname -a panll --version @@ -1052,17 +1085,18 @@ journalctl -u panll -n 50 systemctl status panll systemctl status verisimdb systemctl status burble -``` +---- -## Conclusion +=== Conclusion -This migration guide provides comprehensive instructions for upgrading from PanLL v0.1.x to v0.2.0. The migration includes architectural improvements, new features, and enhanced performance while maintaining backward compatibility for your data. +This migration guide provides comprehensive instructions for upgrading +from PanLL v0.1.x to v0.2.0. The migration includes architectural +improvements, new features, and enhanced performance while maintaining +backward compatibility for your data. -**Key Points**: -- ✅ Backup everything before starting -- ✅ Follow steps in order -- ✅ Test thoroughly after migration -- ✅ Monitor for 24-48 hours -- ✅ Consult backup if issues arise +*Key Points*: - ✅ Backup everything before starting - ✅ Follow steps +in order - ✅ Test thoroughly after migration - ✅ Monitor for 24-48 +hours - ✅ Consult backup if issues arise -For additional assistance, refer to the official documentation or contact support. \ No newline at end of file +For additional assistance, refer to the official documentation or +contact support. diff --git a/docs/reports/audit/pillar-audit-2026-04-15.adoc b/docs/reports/audit/pillar-audit-2026-04-15.adoc new file mode 100644 index 00000000..8f0a9887 --- /dev/null +++ b/docs/reports/audit/pillar-audit-2026-04-15.adoc @@ -0,0 +1,23 @@ +== Gemini Audit Report (M2: Pillar Repo Audits) + +Date: 2026-04-15 Repository: /var/mnt/eclipse/repos/panll + +=== Audit Criteria + +* *Dangerous Patterns*: *CLEAN*. +* *Standards Check*: +** `+.machine_readable/*.a2ml+`: `+AGENTIC.a2ml+`, `+NEUROSYM.a2ml+` +present in `+6a2/+`. +** `+Justfile+`: *PRESENT*. +** `+K9.k9+` / `+coordination.k9+`: *PRESENT* (`+coordination.k9+`). +* *CI/CD Status*: `+.github/workflows+` *PRESENT*. +* *Documentation Parity*: 109 passing tests, 95% completion. +* *Template Residue*: +** `+{{PGP_KEY_URL}}+`, `+{{WEBSITE}}+` found in +`+panel-clades/SECURITY.md+`. + +=== Verdict + +* *CRG Grade*: B +* *Publishable?*: AFTER REPAIR (Fix template placeholders in security +doc). diff --git a/docs/reports/audit/pillar-audit-2026-04-15.md b/docs/reports/audit/pillar-audit-2026-04-15.md deleted file mode 100644 index 33d17222..00000000 --- a/docs/reports/audit/pillar-audit-2026-04-15.md +++ /dev/null @@ -1,19 +0,0 @@ -# Gemini Audit Report (M2: Pillar Repo Audits) -Date: 2026-04-15 -Repository: /var/mnt/eclipse/repos/panll - -## Audit Criteria - -- **Dangerous Patterns**: **CLEAN**. -- **Standards Check**: - - `.machine_readable/*.a2ml`: `AGENTIC.a2ml`, `NEUROSYM.a2ml` present in `6a2/`. - - `Justfile`: **PRESENT**. - - `K9.k9` / `coordination.k9`: **PRESENT** (`coordination.k9`). -- **CI/CD Status**: `.github/workflows` **PRESENT**. -- **Documentation Parity**: 109 passing tests, 95% completion. -- **Template Residue**: - - `{{PGP_KEY_URL}}`, `{{WEBSITE}}` found in `panel-clades/SECURITY.md`. - -## Verdict -- **CRG Grade**: B -- **Publishable?**: AFTER REPAIR (Fix template placeholders in security doc). diff --git a/docs/research/binary-star-neurosymbolic-ide.tex.invariants.adoc b/docs/research/binary-star-neurosymbolic-ide.tex.invariants.adoc new file mode 100644 index 00000000..f5f3b08f --- /dev/null +++ b/docs/research/binary-star-neurosymbolic-ide.tex.invariants.adoc @@ -0,0 +1,93 @@ +== Invariant Path Scan: binary-star-neurosymbolic-ide.tex + +=== Invariant: ip-7e93fc64daa38039 + +⚠️ *ISSUE DETECTED / 🔍 REVIEW REQUIRED* + +*Source Text:* undifferentiated suggestion streams, and an absence of +formal + +*Target Text:* on the boundary between human intent and machine output + +*Invariant Type:* provenance + +*Notes:* auto-generated heuristic suggestion; editable + +[width="5%",cols="100%",options="header",] +|=== +|## Invariant: ip-5a99d2f8cc525508 +|## Invariant: ip-e34ff8435066d123 +|⚠️ *ISSUE DETECTED / 🔍 REVIEW REQUIRED* +|*Source Text:* changes; the human ap +|*Target Text:* or rejects +|*Invariant Type:* provenance +|*Notes:* auto-generated heuristic suggestion; editable +|=== + +=== Invariant: ip-16f4725e3b4fa402 + +⚠️ *ISSUE DETECTED / 🔍 REVIEW REQUIRED* + +*Source Text:* Neural inferences + +*Target Text:* pass through the + +*Invariant Type:* normative_bridge + +*Notes:* auto-generated heuristic suggestion; editable + +[width="5%",cols="100%",options="header",] +|=== +|## Invariant: ip-b85bf0915007810f +|## Invariant: ip-f61a25660eecf82f +|⚠️ *ISSUE DETECTED / 🔍 REVIEW REQUIRED* +|*Source Text:* A constraint ``type latexmath:[\tau] +|*Target Text:* be inhabited’’ can be checked +|*Invariant Type:* normative_bridge +|*Notes:* auto-generated heuristic suggestion; editable +|=== + +=== Invariant: ip-de90d81a5b401102 + +⚠️ *ISSUE DETECTED / 🔍 REVIEW REQUIRED* + +*Source Text:* the function + +*Target Text:* handle every variant of the + +*Invariant Type:* normative_bridge + +*Notes:* auto-generated heuristic suggestion; editable + +[width="5%",cols="100%",options="header",] +|=== +|## Invariant: ip-842a308aa0b75e45 +|## Invariant: ip-0ef31dbb8d87322c +|⚠️ *ISSUE DETECTED / 🔍 REVIEW REQUIRED* +|*Source Text:* to the system and +|*Target Text:* be managed entirely by the operator +|*Invariant Type:* normative_bridge +|*Notes:* auto-generated heuristic suggestion; editable +|=== + +=== Invariant: ip-019edff3a3aba848 + +⚠️ *ISSUE DETECTED / 🔍 REVIEW REQUIRED* + +*Source Text:* controlled user study + +*Target Text:* that the claimed cognitive benefits + +*Invariant Type:* provenance + +*Notes:* auto-generated heuristic suggestion; editable + +[width="5%",cols="100%",] +|=== +|## Invariant: ip-1b7ca7abd610ea70 +|⚠️ *ISSUE DETECTED / 🔍 REVIEW REQUIRED* +|*Source Text:* +|*Target Text:* the directed influence relationships +|*Invariant Type:* provenance +|*Notes:* auto-generated heuristic suggestion; editable +|=== diff --git a/docs/research/binary-star-neurosymbolic-ide.tex.invariants.md b/docs/research/binary-star-neurosymbolic-ide.tex.invariants.md deleted file mode 100644 index 9fb4f67a..00000000 --- a/docs/research/binary-star-neurosymbolic-ide.tex.invariants.md +++ /dev/null @@ -1,145 +0,0 @@ -# Invariant Path Scan: binary-star-neurosymbolic-ide.tex - -## Invariant: ip-7e93fc64daa38039 - -⚠️ **ISSUE DETECTED / 🔍 REVIEW REQUIRED** - -**Source Text:** undifferentiated suggestion streams, and an absence of formal - -**Target Text:** on the boundary between human intent and machine output - -**Invariant Type:** provenance - -**Notes:** auto-generated heuristic suggestion; editable - ---- -## Invariant: ip-5a99d2f8cc525508 - -⚠️ **ISSUE DETECTED / 🔍 REVIEW REQUIRED** - -**Source Text:** human - -**Target Text:** serve as the sole verification layer - -**Invariant Type:** normative_bridge - -**Notes:** auto-generated heuristic suggestion; editable - ---- -## Invariant: ip-e34ff8435066d123 - -⚠️ **ISSUE DETECTED / 🔍 REVIEW REQUIRED** - -**Source Text:** changes; the human ap - -**Target Text:** or rejects - -**Invariant Type:** provenance - -**Notes:** auto-generated heuristic suggestion; editable - ---- -## Invariant: ip-16f4725e3b4fa402 - -⚠️ **ISSUE DETECTED / 🔍 REVIEW REQUIRED** - -**Source Text:** Neural inferences - -**Target Text:** pass through the - -**Invariant Type:** normative_bridge - -**Notes:** auto-generated heuristic suggestion; editable - ---- -## Invariant: ip-b85bf0915007810f - -⚠️ **ISSUE DETECTED / 🔍 REVIEW REQUIRED** - -**Source Text:** All pane state changes - -**Target Text:** originate from \tea{} messages - -**Invariant Type:** normative_bridge - -**Notes:** auto-generated heuristic suggestion; editable - ---- -## Invariant: ip-f61a25660eecf82f - -⚠️ **ISSUE DETECTED / 🔍 REVIEW REQUIRED** - -**Source Text:** A constraint ``type $\tau$ - -**Target Text:** be inhabited'' can be checked - -**Invariant Type:** normative_bridge - -**Notes:** auto-generated heuristic suggestion; editable - ---- -## Invariant: ip-de90d81a5b401102 - -⚠️ **ISSUE DETECTED / 🔍 REVIEW REQUIRED** - -**Source Text:** the \texttt{update} function - -**Target Text:** handle every variant of the - -**Invariant Type:** normative_bridge - -**Notes:** auto-generated heuristic suggestion; editable - ---- -## Invariant: ip-842a308aa0b75e45 - -⚠️ **ISSUE DETECTED / 🔍 REVIEW REQUIRED** - -**Source Text:** ``the next output - -**Target Text:** be compatible with the - -**Invariant Type:** normative_bridge - -**Notes:** auto-generated heuristic suggestion; editable - ---- -## Invariant: ip-0ef31dbb8d87322c - -⚠️ **ISSUE DETECTED / 🔍 REVIEW REQUIRED** - -**Source Text:** to the system and - -**Target Text:** be managed entirely by the operator - -**Invariant Type:** normative_bridge - -**Notes:** auto-generated heuristic suggestion; editable - ---- -## Invariant: ip-019edff3a3aba848 - -⚠️ **ISSUE DETECTED / 🔍 REVIEW REQUIRED** - -**Source Text:** controlled user study - -**Target Text:** that the claimed cognitive benefits - -**Invariant Type:** provenance - -**Notes:** auto-generated heuristic suggestion; editable - ---- -## Invariant: ip-1b7ca7abd610ea70 - -⚠️ **ISSUE DETECTED / 🔍 REVIEW REQUIRED** - -**Source Text:** \Cref{tab:governance} - -**Target Text:** the directed influence relationships - -**Invariant Type:** provenance - -**Notes:** auto-generated heuristic suggestion; editable - ---- diff --git a/docs/status/GAMEDEV-PANEL-TAXONOMY-AUDIT.adoc b/docs/status/GAMEDEV-PANEL-TAXONOMY-AUDIT.adoc new file mode 100644 index 00000000..eecc7b7e --- /dev/null +++ b/docs/status/GAMEDEV-PANEL-TAXONOMY-AUDIT.adoc @@ -0,0 +1,497 @@ +== PanLL Game Dev Panel Taxonomy Audit + +*Author:* Jonathan D.A. Jewell *Date:* 2026-03-14 *Scope:* Map all 48 +existing PanLL panels against IDApTIK game dev requirements, identify +gaps, propose 28 new panels with clade assignments. + +''''' + +=== Table of Contents + +[arabic] +. link:#overview[Overview] +. link:#existing-panel-classification[Existing Panel Classification] +* link:#already-game-dev-relevant-13-panels[Already Game-Dev Relevant +(13)] +* link:#supporting-game-dev-10-panels[Supporting Game Dev (10)] +* link:#not-game-dev-specific-25-panels[Not Game-Dev Specific (25)] +. link:#idaptik-required-categories[IDApTIK Required Categories] +. link:#gap-analysis[Gap Analysis] +. link:#proposed-new-panels-28[Proposed New Panels (28)] +* link:#game-testing-panels-10[Game Testing Panels (10)] +* link:#bridge-panels-8[Bridge Panels (8)] +* link:#game-specific-panels-6[Game-Specific Panels (6)] +* link:#teamcollaboration-panels-4[Team/Collaboration Panels (4)] +. link:#clade-assignments-summary[Clade Assignments Summary] +. link:#clade-kind-coverage[Clade Kind Coverage] +. link:#implementation-priority[Implementation Priority] + +''''' + +=== Overview + +PanLL currently ships 48 panels registered in `+PanelRegistry.res+`. +IDApTIK requires comprehensive game development tooling across six +categories: + +[arabic] +. *Building* — Level design, asset creation, world generation +. *Testing* — Unit, functional, regression, load, soak, compatibility +. *Bridging* — Core PanLL services federated into IDApTIK context +. *Monitoring* — Performance, network, health, multiplayer +. *Collaboration* — Code review, merge coordination, team awareness +. *Debugging* — VM inspection, time-travel, state replay + +Of the existing 48 panels, *13 are directly game-dev relevant*, *10 +support game dev*, and *25 are general-purpose*. This audit identifies +*28 new panels* needed to close the gap. + +''''' + +=== Existing Panel Classification + +==== Already Game-Dev Relevant (13 panels) + +These panels directly serve IDApTIK game development workflows. + +[width="100%",cols="37%,42%,21%",options="header",] +|=== +|Panel ID |Clade Kind |Role +|`+PanelGamePreview+` |Viewer |Live game preview rendering via PixiJS + +|`+PanelVmInspector+` |Viewer / Inspector |VM debugger for IDApTIK’s +custom bytecode + +|`+PanelNetworkTopology+` |Viewer |In-game device network graph +visualisation + +|`+PanelLevelArchitect+` |Builder |Visual level design tool (grid/tile +editor) + +|`+PanelCoprocessors+` |Viewer |Compute backend monitoring (Zig FFI, +WASM) + +|`+PanelMultiplayerMonitor+` |Viewer |Phoenix channel sync monitoring + +|`+PanelDlcWorkshop+` |Builder |DLC content creation and packaging + +|`+PanelUms+` |Builder |Universal Modding Studio hub + +|`+PanelEditorBridge+` |Bridge |External editor federation (VS Code, +Zed) + +|`+PanelBuildDashboard+` |Scanner |Build pipeline monitoring and status + +|`+PanelReleaseManager+` |Builder |Release pipeline orchestration + +|`+PanelPanicAttack+` |Scanner |Stress testing via panic-attack +framework + +|`+PanelObservatory+` |Viewer |System health dashboard +|=== + +==== Supporting Game Dev (10 panels) + +These panels provide infrastructure that game dev panels depend on. + +[width="99%",cols="25%,28%,47%",options="header",] +|=== +|Panel ID |Clade Kind |Game Dev Relevance +|`+PanelTypeLL+` |Service |Type checking for game state schemas + +|`+PanelEchidna+` |Service |Proof verification for Idris2 ABI modules + +|`+PanelBoj+` |Service |Cartridge server (database-mcp, observe-mcp) + +|`+PanelDatabases+` |Database |VeriSimDB for game persistence and save +states + +|`+PanelAi+` |AI |AI provider for guard behaviour analysis + +|`+PanelMigration+` |Viewer |ReScript migration health tracking + +|`+PanelAutomationRouter+` |Directive |Workflow orchestration for +build/deploy + +|`+PanelValenceShell+` |Terminal |Developer terminal for ad-hoc commands + +|`+PanelPlaygrounds+` |Terminal |Code sandbox for prototyping game logic + +|`+PanelCapture+` |Meta |Screenshots and recordings for playtesting +|=== + +==== Not Game-Dev Specific (25 panels) + +These panels serve general PanLL ecosystem functions and are not +directly relevant to IDApTIK game development. + +[cols=",,",options="header",] +|=== +|Panel ID |Clade Kind |Purpose +|`+PanelCloudGuard+` |Scanner |Cloud security posture +|`+PanelVab+` |Builder |Visual Application Builder +|`+PanelFarm+` |Service |Distributed compute farm +|`+PanelFleet+` |Service |gitbot-fleet management +|`+PanelHypatia+` |Service |Neurosymbolic CI intelligence +|`+PanelReposystem+` |Viewer |Repository system overview +|`+PanelAerie+` |Viewer |High-level project dashboard +|`+PanelInterfaces+` |Builder |API interface designer +|`+PanelPlaza+` |Bridge |Community hub +|`+PanelMinter+` |Builder |Token/credential minting +|`+PanelProvisioner+` |Directive |Infrastructure provisioning +|`+PanelVoiceTag+` |Service |Voice annotation +|`+PanelSecurity+` |Scanner |Security audit dashboard +|`+PanelMassPanic+` |Scanner |Mass vulnerability scanning +|`+PanelTsdm+` |Viewer |TSDM methodology tracker +|`+PanelScriptGist+` |Terminal |Script snippet manager +|`+PanelCladeBrowser+` |Viewer |Clade taxonomy browser +|`+PanelTentacles+` |Service |7Tentacles integration +|`+PanelProtocolSquisher+` |Builder |Protocol compression tool +|`+PanelMyLang+` |Builder |Language playground +|`+PanelEvangeliser+` |Service |Outreach automation +|`+PanelHelp+` |Meta |Help and documentation +|`+PanelAmbientOps+` |Directive |AmbientOps orchestration +|`+PanelLanguageForge+` |Builder |Language tooling forge +|`+PanelTangleViz+` |Viewer |Dependency tangle visualisation +|`+PanelSpecBrowser+` |Viewer |Specification browser +|`+PanelVerificationDashboard+` |Viewer |Formal verification status +|=== + +''''' + +=== IDApTIK Required Categories + +IDApTIK needs coverage across six game dev categories. Current state: + +[width="100%",cols="26%,23%,40%,11%",options="header",] +|=== +|Category |Required |Existing Panels |Gap +|*Building* |Level design, world gen, assets, devices |4 +(LevelArchitect, DlcWorkshop, Ums, ReleaseManager) |Parametric gen, +fine-grained editor, asset management, device wiring + +|*Testing* |Unit, functional, regression, load, soak, compat, balance |1 +(PanicAttack — stress only) |All structured testing panels missing + +|*Bridging* |Core PanLL ↔ IDApTIK federation |1 (EditorBridge) |Type, +neurosym, agentic, automation, database, protocol, proofs, scripting + +|*Monitoring* |Perf, network, health, multiplayer |4 (GamePreview, +Coprocessors, MultiplayerMonitor, Observatory) |Perf profiler, soak +monitor, balance analysis + +|*Collaboration* |Code review, merge, team awareness |0 |All +collaboration panels missing + +|*Debugging* |VM debug, time-travel, state inspect |1 (VmInspector) +|Tea_Debug frontend, time-travel, replay +|=== + +*Total gaps: 28 panels needed.* + +''''' + +=== Proposed New Panels (28) + +==== Game Testing Panels (10) + +All new. IDApTIK currently has no structured testing panels beyond +PanicAttack stress tests. + +[width="100%",cols="27%,21%,25%,27%",options="header",] +|=== +|Panel Name |Panel ID |Clade Kind |Description +|Unit Test Runner |`+PanelUnitTestRunner+` |Scanner |Runs ReScript tests +with coverage heatmap and diff-aware testing. Shows per-module pass/fail +with line-level coverage overlay. + +|Functional Tester |`+PanelFunctionalTester+` |Scanner |Scriptable game +workflow simulation (start → hack → win). Defines test scenarios as +composable steps. + +|Regression Guard |`+PanelRegressionGuard+` |Scanner |Snapshot and +golden-file comparison. Answers "`did this change break X?`" with visual +diffs for level output. + +|Performance Profiler |`+PanelPerformanceProfiler+` |Viewer |Frame +budget tracker, GC pressure gauge, memory flamegraphs. Integrates with +PixiJS render loop metrics. + +|Load Tester |`+PanelLoadTester+` |Scanner |Phoenix channel stress +testing and concurrent player simulation. Ramps virtual players to find +breakpoints. + +|Soak Monitor |`+PanelSoakMonitor+` |Viewer |Long-running memory trends +and leak detection. Runs overnight, flags monotonic growth. + +|Compatibility Matrix |`+PanelCompatibilityMatrix+` |Scanner +|Browser/device/resolution test matrix via Playwright. Green/red grid of +target environments. + +|Exploratory Workbench |`+PanelExploratoryWorkbench+` |Viewer |Freeform +play recorder with anomaly flagging. Records player actions and +highlights unexpected states. + +|Beta Feedback Hub |`+PanelBetaFeedbackHub+` |Bridge |Feedback-o-tron +integration with sentiment analysis and triage queues. Connects external +testers to dev workflow. + +|Balance Analyser |`+PanelBalanceAnalyser+` |Viewer |Guard spawn +distributions, Monte Carlo win-rate simulation, difficulty curves. +Validates game balance statistically. +|=== + +==== Bridge Panels (8) + +These federate core PanLL services into IDApTIK context using the L/N/W +(Logic/Neurosymbolic/Widget) pattern. + +[width="100%",cols="15%,10%,12%,17%,26%,20%",options="header",] +|=== +|Panel Name |Panel ID |Clade Kind |L Panel (Logic) |N Panel +(Neurosymbolic) |W Panel (Widget) +|Typing Bridge |`+PanelTypingBridge+` |Bridge |Type constraints for game +state schemas |TypeLL reasoning over constraint satisfaction |Type-safe +config editor with validation + +|Neurosymbolic Bridge |`+PanelNeurosymBridge+` |Bridge |Guard behaviour +rules (Idris2 specs) |ECHIDNA reasoning over behaviour trees |Behaviour +tree visualisation and editing + +|Agentic Bridge |`+PanelAgenticBridge+` |Bridge |Test agent parameters +and bounds |AI agent OODA loop execution |Agent execution results and +replay + +|Automation Bridge |`+PanelAutomationBridge+` |Bridge |CI/CD pipeline +rules and triggers |Pipeline reasoning and optimisation |Build/deploy +status with drill-down + +|Database Bridge |`+PanelDatabaseBridge+` |Bridge |VeriSimDB schema +constraints |Query optimisation suggestions |Game state persistence +viewer + +|Protocol Bridge |`+PanelProtocolBridge+` |Bridge |Sync protocol rules +(Phoenix channels) |Protocol analysis and anomaly detection |Channel +status and latency gauges + +|Proofs Bridge |`+PanelProofsBridge+` |Bridge |Proven repo interface +specifications |ECHIDNA formal verification |Proof status badges and +progress + +|Scripting Bridge |`+PanelScriptingBridge+` |Bridge |VM instruction +constraints and limits |Script analysis (dead code, complexity) |VM +scripting REPL with autocomplete +|=== + +==== Game-Specific Panels (6) + +[width="100%",cols="27%,21%,25%,27%",options="header",] +|=== +|Panel Name |Panel ID |Clade Kind |Description +|Generator Mode |`+PanelGeneratorMode+` |Builder |Parametric world +builder with sliders and toggles. Generates level templates from +constraint parameters (room count, difficulty, device density). + +|Architect Mode |`+PanelArchitectMode+` |Builder |PixiJS fine-grained +editor with L/N/W integration. Tile-by-tile placement, layer management, +object properties. Extends PanelLevelArchitect with precision tools. + +|Guard AI Tuner |`+PanelGuardAiTuner+` |Viewer |Guard patrol path +editor, alert threshold sliders, spawn rate curves. Visualises guard FOV +cones and patrol timing. + +|Device Network Designer |`+PanelDeviceNetworkDesigner+` |Builder |Wire +devices together, configure security levels, set network topology. +Drag-and-drop device placement with logical connection validation. + +|Asset Manager |`+PanelAssetManager+` |Loader |PixiJS sprite sheets, +sound files, level templates. Search, tag, preview, and version game +assets. Tracks asset usage across levels. + +|Playtest Recorder |`+PanelPlaytestRecorder+` |Viewer |Record and replay +game sessions. Annotate key moments, flag bugs, export clips. Integrates +with Capture panel for screenshots. +|=== + +==== Team/Collaboration Panels (4) + +[width="100%",cols="27%,21%,25%,27%",options="header",] +|=== +|Panel Name |Panel ID |Clade Kind |Description +|Code Review |`+PanelCodeReview+` |Scanner |PR review with inline +comments, approval gates, and diff viewer. Integrates with GitHub/GitLab +MCP. + +|Merge Coordinator |`+PanelMergeCoordinator+` |Directive |Branch +management, conflict resolution assistant, merge queue. Prevents broken +merges with pre-merge checks. + +|Team Dashboard |`+PanelTeamDashboard+` |Viewer |Who is working on what, +activity feed, contributor stats. Shows panel usage patterns across +team. + +|Debugging Workbench |`+PanelDebuggingWorkbench+` |Inspector |Tea_Debug +frontend with time-travel debugging, state inspection, and message +replay. Steps through TEA update cycles. +|=== + +''''' + +=== Clade Assignments Summary + +==== New Panels by Clade Kind + +[width="100%",cols="46%,25%,29%",options="header",] +|=== +|Clade Kind |Count |Panels +|*Scanner* |6 |UnitTestRunner, FunctionalTester, RegressionGuard, +LoadTester, CompatibilityMatrix, CodeReview + +|*Viewer* |7 |PerformanceProfiler, SoakMonitor, ExploratoryWorkbench, +BalanceAnalyser, GuardAiTuner, PlaytestRecorder, TeamDashboard + +|*Bridge* |9 |BetaFeedbackHub, TypingBridge, NeurosymBridge, +AgenticBridge, AutomationBridge, DatabaseBridge, ProtocolBridge, +ProofsBridge, ScriptingBridge + +|*Builder* |3 |GeneratorMode, ArchitectMode, DeviceNetworkDesigner + +|*Directive* |1 |MergeCoordinator + +|*Inspector* |1 |DebuggingWorkbench + +|*Loader* |1 |AssetManager + +|*Total* |*28* | +|=== + +==== Full Panel Count After Implementation + +[cols=",,,",options="header",] +|=== +|Category |Existing |New |Total +|All panels |48 |28 |*76* +|Game-dev relevant |13 |28 |*41* +|Game-dev supporting |10 |0 |*10* +|General-purpose |25 |0 |*25* +|=== + +''''' + +=== Clade Kind Coverage + +The existing 13 clade kinds cover all 28 proposed panels. *No new clade +kind is needed.* + +[cols=",,,,",options="header",] +|=== +|Tag |Clade Kind |Existing Uses |New Uses |Total +|1 |Viewer |12 |7 |19 +|2 |Builder |8 |3 |11 +|3 |Scanner |5 |6 |11 +|4 |Service |7 |0 |7 +|5 |Terminal |3 |0 |3 +|6 |Bridge |2 |9 |11 +|7 |Database |1 |0 |1 +|8 |AI |1 |0 |1 +|9 |Directive |2 |1 |3 +|10 |Inspector |0 |1 |1 +|11 |Meta |2 |0 |2 +|12 |Loader |0 |1 |1 +|13 |Config |0 |0 |0 +|=== + +*Note:* Inspector (tag 10) and Loader (tag 12) are used for the first +time by new panels. AssetManager is assigned Loader because its primary +function is asset retrieval and indexing rather than asset creation. If +asset creation becomes its dominant use case, reclassify to Builder. + +''''' + +=== Implementation Priority + +==== Phase 1 — Immediate (Game dev panels, highest priority) + +These are required before IDApTIK can move beyond prototype-level +tooling. + +*Testing panels (10):* + +[cols=",,",options="header",] +|=== +|Panel |Depends On |Estimated Effort +|`+PanelUnitTestRunner+` |ReScript test framework |Medium +|`+PanelFunctionalTester+` |Game workflow API |Medium +|`+PanelRegressionGuard+` |Snapshot infrastructure |Medium +|`+PanelPerformanceProfiler+` |PixiJS metrics hooks |High +|`+PanelLoadTester+` |Phoenix channel API |High +|`+PanelSoakMonitor+` |Long-running process support |Medium +|`+PanelCompatibilityMatrix+` |Playwright MCP |High +|`+PanelExploratoryWorkbench+` |Game session recording |Medium +|`+PanelBetaFeedbackHub+` |Feedback-o-tron API |Low +|`+PanelBalanceAnalyser+` |Game state statistics API |High +|=== + +*Bridge panels (8):* + +[cols=",,",options="header",] +|=== +|Panel |Depends On |Estimated Effort +|`+PanelTypingBridge+` |PanelTypeLL service API |Medium +|`+PanelNeurosymBridge+` |PanelEchidna service API |High +|`+PanelAgenticBridge+` |PanelAi service API |Medium +|`+PanelAutomationBridge+` |PanelAutomationRouter API |Low +|`+PanelDatabaseBridge+` |PanelDatabases / VeriSimDB |Medium +|`+PanelProtocolBridge+` |Phoenix channel introspection |High +|`+PanelProofsBridge+` |proven repo + ECHIDNA |High +|`+PanelScriptingBridge+` |PanelVmInspector + VM API |Medium +|=== + +*Core game panels (2):* + +[cols=",,",options="header",] +|=== +|Panel |Depends On |Estimated Effort +|`+PanelGeneratorMode+` |Level constraint schema |High +|`+PanelArchitectMode+` |PixiJS editor framework |High +|=== + +==== Phase 2 — Next + +[cols=",,",options="header",] +|=== +|Panel |Depends On |Estimated Effort +|`+PanelGuardAiTuner+` |Guard AI API |Medium +|`+PanelDeviceNetworkDesigner+` |Device graph model |Medium +|`+PanelAssetManager+` |Asset pipeline |Medium +|`+PanelPlaytestRecorder+` |Session recording infra |Medium +|`+PanelDebuggingWorkbench+` |Tea_Debug protocol |High +|=== + +==== Phase 3 — Later + +[cols=",,",options="header",] +|=== +|Panel |Depends On |Estimated Effort +|`+PanelCodeReview+` |GitHub/GitLab MCP |Medium +|`+PanelMergeCoordinator+` |Git branch API |Medium +|`+PanelTeamDashboard+` |Activity tracking |Low +|=== + +''''' + +=== Notes + +* *Panel naming:* All panel IDs use the `+Panel+` prefix per PanLL +convention in `+PanelRegistry.res+`. +* *L/N/W pattern:* Bridge panels follow the Logic/Neurosymbolic/Widget +triple established in the PanLL architecture. Each bridge panel exposes +three sub-panels (L, N, W) that can be arranged independently in the +workspace. +* *Clade kind assignment:* Based on primary function. Some panels have +secondary roles (e.g., AssetManager is Loader but has Builder aspects). +The primary clade determines placement in the clade browser. +* *No new clade kinds:* The existing 13 kinds (Viewer, Builder, Scanner, +Service, Terminal, Bridge, Database, AI, Directive, Inspector, Meta, +Loader, Config) are sufficient. Inspector and Loader see their first use +with these new panels. diff --git a/docs/status/GAMEDEV-PANEL-TAXONOMY-AUDIT.md b/docs/status/GAMEDEV-PANEL-TAXONOMY-AUDIT.md deleted file mode 100644 index 662bfccb..00000000 --- a/docs/status/GAMEDEV-PANEL-TAXONOMY-AUDIT.md +++ /dev/null @@ -1,311 +0,0 @@ - - - -# PanLL Game Dev Panel Taxonomy Audit - -**Author:** Jonathan D.A. Jewell -**Date:** 2026-03-14 -**Scope:** Map all 48 existing PanLL panels against IDApTIK game dev requirements, identify gaps, propose 28 new panels with clade assignments. - ---- - -## Table of Contents - -1. [Overview](#overview) -2. [Existing Panel Classification](#existing-panel-classification) - - [Already Game-Dev Relevant (13)](#already-game-dev-relevant-13-panels) - - [Supporting Game Dev (10)](#supporting-game-dev-10-panels) - - [Not Game-Dev Specific (25)](#not-game-dev-specific-25-panels) -3. [IDApTIK Required Categories](#idaptik-required-categories) -4. [Gap Analysis](#gap-analysis) -5. [Proposed New Panels (28)](#proposed-new-panels-28) - - [Game Testing Panels (10)](#game-testing-panels-10) - - [Bridge Panels (8)](#bridge-panels-8) - - [Game-Specific Panels (6)](#game-specific-panels-6) - - [Team/Collaboration Panels (4)](#teamcollaboration-panels-4) -6. [Clade Assignments Summary](#clade-assignments-summary) -7. [Clade Kind Coverage](#clade-kind-coverage) -8. [Implementation Priority](#implementation-priority) - ---- - -## Overview - -PanLL currently ships 48 panels registered in `PanelRegistry.res`. IDApTIK requires comprehensive game development tooling across six categories: - -1. **Building** — Level design, asset creation, world generation -2. **Testing** — Unit, functional, regression, load, soak, compatibility -3. **Bridging** — Core PanLL services federated into IDApTIK context -4. **Monitoring** — Performance, network, health, multiplayer -5. **Collaboration** — Code review, merge coordination, team awareness -6. **Debugging** — VM inspection, time-travel, state replay - -Of the existing 48 panels, **13 are directly game-dev relevant**, **10 support game dev**, and **25 are general-purpose**. This audit identifies **28 new panels** needed to close the gap. - ---- - -## Existing Panel Classification - -### Already Game-Dev Relevant (13 panels) - -These panels directly serve IDApTIK game development workflows. - -| Panel ID | Clade Kind | Role | -|----------|------------|------| -| `PanelGamePreview` | Viewer | Live game preview rendering via PixiJS | -| `PanelVmInspector` | Viewer / Inspector | VM debugger for IDApTIK's custom bytecode | -| `PanelNetworkTopology` | Viewer | In-game device network graph visualisation | -| `PanelLevelArchitect` | Builder | Visual level design tool (grid/tile editor) | -| `PanelCoprocessors` | Viewer | Compute backend monitoring (Zig FFI, WASM) | -| `PanelMultiplayerMonitor` | Viewer | Phoenix channel sync monitoring | -| `PanelDlcWorkshop` | Builder | DLC content creation and packaging | -| `PanelUms` | Builder | Universal Modding Studio hub | -| `PanelEditorBridge` | Bridge | External editor federation (VS Code, Zed) | -| `PanelBuildDashboard` | Scanner | Build pipeline monitoring and status | -| `PanelReleaseManager` | Builder | Release pipeline orchestration | -| `PanelPanicAttack` | Scanner | Stress testing via panic-attack framework | -| `PanelObservatory` | Viewer | System health dashboard | - -### Supporting Game Dev (10 panels) - -These panels provide infrastructure that game dev panels depend on. - -| Panel ID | Clade Kind | Game Dev Relevance | -|----------|------------|--------------------| -| `PanelTypeLL` | Service | Type checking for game state schemas | -| `PanelEchidna` | Service | Proof verification for Idris2 ABI modules | -| `PanelBoj` | Service | Cartridge server (database-mcp, observe-mcp) | -| `PanelDatabases` | Database | VeriSimDB for game persistence and save states | -| `PanelAi` | AI | AI provider for guard behaviour analysis | -| `PanelMigration` | Viewer | ReScript migration health tracking | -| `PanelAutomationRouter` | Directive | Workflow orchestration for build/deploy | -| `PanelValenceShell` | Terminal | Developer terminal for ad-hoc commands | -| `PanelPlaygrounds` | Terminal | Code sandbox for prototyping game logic | -| `PanelCapture` | Meta | Screenshots and recordings for playtesting | - -### Not Game-Dev Specific (25 panels) - -These panels serve general PanLL ecosystem functions and are not directly relevant to IDApTIK game development. - -| Panel ID | Clade Kind | Purpose | -|----------|------------|---------| -| `PanelCloudGuard` | Scanner | Cloud security posture | -| `PanelVab` | Builder | Visual Application Builder | -| `PanelFarm` | Service | Distributed compute farm | -| `PanelFleet` | Service | gitbot-fleet management | -| `PanelHypatia` | Service | Neurosymbolic CI intelligence | -| `PanelReposystem` | Viewer | Repository system overview | -| `PanelAerie` | Viewer | High-level project dashboard | -| `PanelInterfaces` | Builder | API interface designer | -| `PanelPlaza` | Bridge | Community hub | -| `PanelMinter` | Builder | Token/credential minting | -| `PanelProvisioner` | Directive | Infrastructure provisioning | -| `PanelVoiceTag` | Service | Voice annotation | -| `PanelSecurity` | Scanner | Security audit dashboard | -| `PanelMassPanic` | Scanner | Mass vulnerability scanning | -| `PanelTsdm` | Viewer | TSDM methodology tracker | -| `PanelScriptGist` | Terminal | Script snippet manager | -| `PanelCladeBrowser` | Viewer | Clade taxonomy browser | -| `PanelTentacles` | Service | 7Tentacles integration | -| `PanelProtocolSquisher` | Builder | Protocol compression tool | -| `PanelMyLang` | Builder | Language playground | -| `PanelEvangeliser` | Service | Outreach automation | -| `PanelHelp` | Meta | Help and documentation | -| `PanelAmbientOps` | Directive | AmbientOps orchestration | -| `PanelLanguageForge` | Builder | Language tooling forge | -| `PanelTangleViz` | Viewer | Dependency tangle visualisation | -| `PanelSpecBrowser` | Viewer | Specification browser | -| `PanelVerificationDashboard` | Viewer | Formal verification status | - ---- - -## IDApTIK Required Categories - -IDApTIK needs coverage across six game dev categories. Current state: - -| Category | Required | Existing Panels | Gap | -|----------|----------|-----------------|-----| -| **Building** | Level design, world gen, assets, devices | 4 (LevelArchitect, DlcWorkshop, Ums, ReleaseManager) | Parametric gen, fine-grained editor, asset management, device wiring | -| **Testing** | Unit, functional, regression, load, soak, compat, balance | 1 (PanicAttack — stress only) | All structured testing panels missing | -| **Bridging** | Core PanLL ↔ IDApTIK federation | 1 (EditorBridge) | Type, neurosym, agentic, automation, database, protocol, proofs, scripting | -| **Monitoring** | Perf, network, health, multiplayer | 4 (GamePreview, Coprocessors, MultiplayerMonitor, Observatory) | Perf profiler, soak monitor, balance analysis | -| **Collaboration** | Code review, merge, team awareness | 0 | All collaboration panels missing | -| **Debugging** | VM debug, time-travel, state inspect | 1 (VmInspector) | Tea_Debug frontend, time-travel, replay | - -**Total gaps: 28 panels needed.** - ---- - -## Proposed New Panels (28) - -### Game Testing Panels (10) - -All new. IDApTIK currently has no structured testing panels beyond PanicAttack stress tests. - -| Panel Name | Panel ID | Clade Kind | Description | -|------------|----------|------------|-------------| -| Unit Test Runner | `PanelUnitTestRunner` | Scanner | Runs ReScript tests with coverage heatmap and diff-aware testing. Shows per-module pass/fail with line-level coverage overlay. | -| Functional Tester | `PanelFunctionalTester` | Scanner | Scriptable game workflow simulation (start → hack → win). Defines test scenarios as composable steps. | -| Regression Guard | `PanelRegressionGuard` | Scanner | Snapshot and golden-file comparison. Answers "did this change break X?" with visual diffs for level output. | -| Performance Profiler | `PanelPerformanceProfiler` | Viewer | Frame budget tracker, GC pressure gauge, memory flamegraphs. Integrates with PixiJS render loop metrics. | -| Load Tester | `PanelLoadTester` | Scanner | Phoenix channel stress testing and concurrent player simulation. Ramps virtual players to find breakpoints. | -| Soak Monitor | `PanelSoakMonitor` | Viewer | Long-running memory trends and leak detection. Runs overnight, flags monotonic growth. | -| Compatibility Matrix | `PanelCompatibilityMatrix` | Scanner | Browser/device/resolution test matrix via Playwright. Green/red grid of target environments. | -| Exploratory Workbench | `PanelExploratoryWorkbench` | Viewer | Freeform play recorder with anomaly flagging. Records player actions and highlights unexpected states. | -| Beta Feedback Hub | `PanelBetaFeedbackHub` | Bridge | Feedback-o-tron integration with sentiment analysis and triage queues. Connects external testers to dev workflow. | -| Balance Analyser | `PanelBalanceAnalyser` | Viewer | Guard spawn distributions, Monte Carlo win-rate simulation, difficulty curves. Validates game balance statistically. | - -### Bridge Panels (8) - -These federate core PanLL services into IDApTIK context using the L/N/W (Logic/Neurosymbolic/Widget) pattern. - -| Panel Name | Panel ID | Clade Kind | L Panel (Logic) | N Panel (Neurosymbolic) | W Panel (Widget) | -|------------|----------|------------|-----------------|-------------------------|-------------------| -| Typing Bridge | `PanelTypingBridge` | Bridge | Type constraints for game state schemas | TypeLL reasoning over constraint satisfaction | Type-safe config editor with validation | -| Neurosymbolic Bridge | `PanelNeurosymBridge` | Bridge | Guard behaviour rules (Idris2 specs) | ECHIDNA reasoning over behaviour trees | Behaviour tree visualisation and editing | -| Agentic Bridge | `PanelAgenticBridge` | Bridge | Test agent parameters and bounds | AI agent OODA loop execution | Agent execution results and replay | -| Automation Bridge | `PanelAutomationBridge` | Bridge | CI/CD pipeline rules and triggers | Pipeline reasoning and optimisation | Build/deploy status with drill-down | -| Database Bridge | `PanelDatabaseBridge` | Bridge | VeriSimDB schema constraints | Query optimisation suggestions | Game state persistence viewer | -| Protocol Bridge | `PanelProtocolBridge` | Bridge | Sync protocol rules (Phoenix channels) | Protocol analysis and anomaly detection | Channel status and latency gauges | -| Proofs Bridge | `PanelProofsBridge` | Bridge | Proven repo interface specifications | ECHIDNA formal verification | Proof status badges and progress | -| Scripting Bridge | `PanelScriptingBridge` | Bridge | VM instruction constraints and limits | Script analysis (dead code, complexity) | VM scripting REPL with autocomplete | - -### Game-Specific Panels (6) - -| Panel Name | Panel ID | Clade Kind | Description | -|------------|----------|------------|-------------| -| Generator Mode | `PanelGeneratorMode` | Builder | Parametric world builder with sliders and toggles. Generates level templates from constraint parameters (room count, difficulty, device density). | -| Architect Mode | `PanelArchitectMode` | Builder | PixiJS fine-grained editor with L/N/W integration. Tile-by-tile placement, layer management, object properties. Extends PanelLevelArchitect with precision tools. | -| Guard AI Tuner | `PanelGuardAiTuner` | Viewer | Guard patrol path editor, alert threshold sliders, spawn rate curves. Visualises guard FOV cones and patrol timing. | -| Device Network Designer | `PanelDeviceNetworkDesigner` | Builder | Wire devices together, configure security levels, set network topology. Drag-and-drop device placement with logical connection validation. | -| Asset Manager | `PanelAssetManager` | Loader | PixiJS sprite sheets, sound files, level templates. Search, tag, preview, and version game assets. Tracks asset usage across levels. | -| Playtest Recorder | `PanelPlaytestRecorder` | Viewer | Record and replay game sessions. Annotate key moments, flag bugs, export clips. Integrates with Capture panel for screenshots. | - -### Team/Collaboration Panels (4) - -| Panel Name | Panel ID | Clade Kind | Description | -|------------|----------|------------|-------------| -| Code Review | `PanelCodeReview` | Scanner | PR review with inline comments, approval gates, and diff viewer. Integrates with GitHub/GitLab MCP. | -| Merge Coordinator | `PanelMergeCoordinator` | Directive | Branch management, conflict resolution assistant, merge queue. Prevents broken merges with pre-merge checks. | -| Team Dashboard | `PanelTeamDashboard` | Viewer | Who is working on what, activity feed, contributor stats. Shows panel usage patterns across team. | -| Debugging Workbench | `PanelDebuggingWorkbench` | Inspector | Tea_Debug frontend with time-travel debugging, state inspection, and message replay. Steps through TEA update cycles. | - ---- - -## Clade Assignments Summary - -### New Panels by Clade Kind - -| Clade Kind | Count | Panels | -|------------|-------|--------| -| **Scanner** | 6 | UnitTestRunner, FunctionalTester, RegressionGuard, LoadTester, CompatibilityMatrix, CodeReview | -| **Viewer** | 7 | PerformanceProfiler, SoakMonitor, ExploratoryWorkbench, BalanceAnalyser, GuardAiTuner, PlaytestRecorder, TeamDashboard | -| **Bridge** | 9 | BetaFeedbackHub, TypingBridge, NeurosymBridge, AgenticBridge, AutomationBridge, DatabaseBridge, ProtocolBridge, ProofsBridge, ScriptingBridge | -| **Builder** | 3 | GeneratorMode, ArchitectMode, DeviceNetworkDesigner | -| **Directive** | 1 | MergeCoordinator | -| **Inspector** | 1 | DebuggingWorkbench | -| **Loader** | 1 | AssetManager | -| **Total** | **28** | | - -### Full Panel Count After Implementation - -| Category | Existing | New | Total | -|----------|----------|-----|-------| -| All panels | 48 | 28 | **76** | -| Game-dev relevant | 13 | 28 | **41** | -| Game-dev supporting | 10 | 0 | **10** | -| General-purpose | 25 | 0 | **25** | - ---- - -## Clade Kind Coverage - -The existing 13 clade kinds cover all 28 proposed panels. **No new clade kind is needed.** - -| Tag | Clade Kind | Existing Uses | New Uses | Total | -|-----|------------|---------------|----------|-------| -| 1 | Viewer | 12 | 7 | 19 | -| 2 | Builder | 8 | 3 | 11 | -| 3 | Scanner | 5 | 6 | 11 | -| 4 | Service | 7 | 0 | 7 | -| 5 | Terminal | 3 | 0 | 3 | -| 6 | Bridge | 2 | 9 | 11 | -| 7 | Database | 1 | 0 | 1 | -| 8 | AI | 1 | 0 | 1 | -| 9 | Directive | 2 | 1 | 3 | -| 10 | Inspector | 0 | 1 | 1 | -| 11 | Meta | 2 | 0 | 2 | -| 12 | Loader | 0 | 1 | 1 | -| 13 | Config | 0 | 0 | 0 | - -**Note:** Inspector (tag 10) and Loader (tag 12) are used for the first time by new panels. AssetManager is assigned Loader because its primary function is asset retrieval and indexing rather than asset creation. If asset creation becomes its dominant use case, reclassify to Builder. - ---- - -## Implementation Priority - -### Phase 1 — Immediate (Game dev panels, highest priority) - -These are required before IDApTIK can move beyond prototype-level tooling. - -**Testing panels (10):** - -| Panel | Depends On | Estimated Effort | -|-------|-----------|------------------| -| `PanelUnitTestRunner` | ReScript test framework | Medium | -| `PanelFunctionalTester` | Game workflow API | Medium | -| `PanelRegressionGuard` | Snapshot infrastructure | Medium | -| `PanelPerformanceProfiler` | PixiJS metrics hooks | High | -| `PanelLoadTester` | Phoenix channel API | High | -| `PanelSoakMonitor` | Long-running process support | Medium | -| `PanelCompatibilityMatrix` | Playwright MCP | High | -| `PanelExploratoryWorkbench` | Game session recording | Medium | -| `PanelBetaFeedbackHub` | Feedback-o-tron API | Low | -| `PanelBalanceAnalyser` | Game state statistics API | High | - -**Bridge panels (8):** - -| Panel | Depends On | Estimated Effort | -|-------|-----------|------------------| -| `PanelTypingBridge` | PanelTypeLL service API | Medium | -| `PanelNeurosymBridge` | PanelEchidna service API | High | -| `PanelAgenticBridge` | PanelAi service API | Medium | -| `PanelAutomationBridge` | PanelAutomationRouter API | Low | -| `PanelDatabaseBridge` | PanelDatabases / VeriSimDB | Medium | -| `PanelProtocolBridge` | Phoenix channel introspection | High | -| `PanelProofsBridge` | proven repo + ECHIDNA | High | -| `PanelScriptingBridge` | PanelVmInspector + VM API | Medium | - -**Core game panels (2):** - -| Panel | Depends On | Estimated Effort | -|-------|-----------|------------------| -| `PanelGeneratorMode` | Level constraint schema | High | -| `PanelArchitectMode` | PixiJS editor framework | High | - -### Phase 2 — Next - -| Panel | Depends On | Estimated Effort | -|-------|-----------|------------------| -| `PanelGuardAiTuner` | Guard AI API | Medium | -| `PanelDeviceNetworkDesigner` | Device graph model | Medium | -| `PanelAssetManager` | Asset pipeline | Medium | -| `PanelPlaytestRecorder` | Session recording infra | Medium | -| `PanelDebuggingWorkbench` | Tea_Debug protocol | High | - -### Phase 3 — Later - -| Panel | Depends On | Estimated Effort | -|-------|-----------|------------------| -| `PanelCodeReview` | GitHub/GitLab MCP | Medium | -| `PanelMergeCoordinator` | Git branch API | Medium | -| `PanelTeamDashboard` | Activity tracking | Low | - ---- - -## Notes - -- **Panel naming:** All panel IDs use the `Panel` prefix per PanLL convention in `PanelRegistry.res`. -- **L/N/W pattern:** Bridge panels follow the Logic/Neurosymbolic/Widget triple established in the PanLL architecture. Each bridge panel exposes three sub-panels (L, N, W) that can be arranged independently in the workspace. -- **Clade kind assignment:** Based on primary function. Some panels have secondary roles (e.g., AssetManager is Loader but has Builder aspects). The primary clade determines placement in the clade browser. -- **No new clade kinds:** The existing 13 kinds (Viewer, Builder, Scanner, Service, Terminal, Bridge, Database, AI, Directive, Inspector, Meta, Loader, Config) are sufficient. Inspector and Loader see their first use with these new panels. diff --git a/docs/status/PANLL-COMPLETE-STATUS-2026-02-11.adoc b/docs/status/PANLL-COMPLETE-STATUS-2026-02-11.adoc new file mode 100644 index 00000000..e129b5bb --- /dev/null +++ b/docs/status/PANLL-COMPLETE-STATUS-2026-02-11.adoc @@ -0,0 +1,344 @@ +== PANLL: Complete Project Status, Priority TODO Plan & Thread Decomposition + +== Generated: 2026-02-11 (KEEP UPDATED EACH SESSION) + +== Author: Codex (GPT-5) audit pass + +== Purpose: Single source of truth for what is actually done vs what still needs work + +''''' + +=== HOW TO USE THIS DOCUMENT + +Read this document fully before starting new work on PanLL. + +It records: - what is genuinely working now, - what is claimed but not +yet true, - what is currently broken, - and the next tasks in strict +priority order. + +Move completed tasks into the TO-DONE section at the bottom as work +lands. + +''''' + +=== TABLE OF CONTENTS + +[arabic] +. link:#1-honest-status-assessment[Honest Status Assessment] +. link:#2-what-is-actually-done[What Is Actually Done] +. link:#3-what-is-claimed-but-not-done[What Is Claimed But Not Done] +. link:#4-what-is-broken-right-now[What Is Broken Right Now] +. link:++#5-code-quality--risk-notes++[Code Quality & Risk Notes] +. link:#6-complete-task-list-priority-ordered[Complete Task List +(Priority Ordered)] +. link:#7-thread-decomposition[Thread Decomposition] +. link:#8-to-done-completed-items[TO-DONE (Completed Items)] +. link:#9-revision-history[Revision History] + +''''' + +=== 1. HONEST STATUS ASSESSMENT + +*Estimated completion: ~76% (not 95%)* + +Reasoning: - Core TEA modules exist and have unit tests. - Tauri backend +compiles. - Core product loop is not release-ready yet, but frontend +ReScript compile now passes. - Backend command behavior is partly +placeholder logic. - Coverage is concentrated in TEA internals, not full +application behavior. + +==== Reality Snapshot (2026-02-11) + +[width="100%",cols="33%,25%,22%,20%",options="header",] +|=== +|Component |Claimed |Actual |Notes +|Custom TEA runtime |Complete |~80% |Modules exist, tests pass, but app +lifecycle/rendering is still described as partial in tests + +|Frontend ReScript build |Implied healthy |*Working* +|`+npm run res:build+` passes (warnings only) + +|Tauri backend commands |Working |~45% |Commands are wired, but +`+main.rs+` still has TODO placeholder implementations + +|Event-chain import |Working |~92% |Parser/update flow is real + +panic-attacker integration path now wired + +|State persistence |Roadmap says TODO |*Implemented* +|`+src/Storage.res+` has load/save/clear via localStorage and is wired +from app init/update + +|Keyboard shortcuts |Roadmap says TODO |*Implemented (core set)* +|Ctrl+Shift+L/N/B/W handlers exist in subscriptions + +|Testing |36 tests passing |True, improving |TEA tests + panic-attacker +event-chain parser tests now pass + +|Coverage |87-91% |Misleading headline |Current run: Branch 86.2%, Line +51.4% across only TEA files under test +|=== + +''''' + +=== 2. WHAT IS ACTUALLY DONE + +Verified in code and/or command execution: + +==== Architecture & Core + +* Custom TEA modules exist: `+src/tea/Tea_Cmd.res+`, +`+src/tea/Tea_Sub.res+`, `+src/tea/Tea_App.res+`, +`+src/tea/Tea_Render.res+`, `+src/tea/Tea_Vdom.res+`, +`+src/tea/Tea_Html.res+`. +* Centralized model/message/update/view wiring exists: +`+src/Model.res+`, `+src/Msg.res+`, `+src/Update.res+`, +`+src/View.res+`, `+src/App.res+`. + +==== Product Features Implemented + +* Event-chain parse/import path implemented in +`+src/core/EventChain.res+` and `+src/components/PaneW.res+`. +* File import command path implemented in `+src/commands/TauriCmd.res+` +and update handler (`+PaneW(ImportEventChainFile)+` in +`+src/Update.res+`). +* panic-attacker integration added: +** `+Import latest panic-attacker+` path (auto-detect latest report in +panic-attacker reports dir). +** `+Load panic-attacker Report+` path (select report file, convert, +import). +** Backend runs `+panic-attack panll+` when available and falls back to +direct assault-report conversion when binary lacks that subcommand. +* Anti-crash flow and token gating wired (`+src/core/AntiCrash.res+`, +`+src/Update.res+`). +* localStorage persistence implemented and auto-save wired +(`+src/Storage.res+`, `+src/App.res+`, `+src/Update.res+`). +* Keyboard shortcut subscriptions implemented +(`+src/SubscriptionsFixed.res+`). +* BEAM runtime scaffold implemented in `+beam/panll_beam+` with +protocol-selectable API surface: +** HTTP via Bandit/Plug (`+/healthz+`, `+/v1/status+`) +** GraphQL via Absinthe (`+/graphql+`, `+/graphiql+`) +** gRPC via `+panll.v1.StatusService/GetStatus+` +** Runtime selection via `+PANLL_BEAM_APIS+` (`+http+`, `+graphql+`, +`+grpc+`) +* Hypatia workflow parsing fixed to read scanner envelope +(`+.findings+`) correctly for counts/severity in +`+.github/workflows/hypatia-scan.yml+`, with explicit +`+FLEET_GITHUB_TOKEN+` gate for cross-repo submission. +* Runtime stack scaffolding added under `+runtime/+`: +** Chainguard-based `+Containerfile+` for BEAM release +** `+compose.toml+` including `+svalinn+`, `+vordr+`, `+selur+`, +`+rokur+`, and `+panll+` +** scripts for build/pack/verify via Cerro Torre and selur-compose +up/down + +==== Build/Test Health + +* `+deno task test+`: *36 passed, 0 failed*. +* `+deno task test:coverage+`: Branch *86.2%*, Line *51.4%*, scoped to +TEA files in current tests. +* `+npm run res:clean && npm run res:build+`: passes (warnings only). +* `+cargo check+` in `+src-tauri+`: passes (with minor unused-variable +warnings). + +''''' + +=== 3. WHAT IS CLAIMED BUT NOT DONE + +==== A) Build/Runtime Readiness Claims + +[width="100%",cols="40%,60%",options="header",] +|=== +|Claim |Reality +|`+v0.1.0 ... 95% complete+` (`+README.adoc+`, `+ROADMAP.adoc+`) +|Frontend now compiles, but release readiness is still overstated due +backend stubs + thin integration coverage + +|Tauri commands "`working`" |Wired but logic is placeholder in +`+src-tauri/src/main.rs+` + +|Coverage badge-level confidence |Real app line coverage is low relative +to whole codebase; only selected TEA modules are covered +|=== + +==== B) Roadmap Drift (Needs Cleanup) + +Roadmap currently marks these as TODO, but code shows they are already +present: - State persistence (`+src/Storage.res+`) - Keyboard shortcuts +(`+src/SubscriptionsFixed.res+`, plus docs in `+README.adoc+`) + +==== C) "`Production Ready`" Documentation Drift + +* `+docs/TEA_GUIDE.md+` reports `+Status: Production Ready+`, but: +** ReScript build passes, but production-quality integration coverage is +still missing. +** Test files explicitly note missing full lifecycle/render pipeline +coverage (`+tests/tea_app_test.js+`, `+tests/tea_render_test.js+`). + +''''' + +=== 4. WHAT IS BROKEN RIGHT NOW + +==== 4.1 Panic-Attacker Binary Version Drift + +* In the original dev environment, the `+panic-attack+` binary (from the +`+panic-attacker+` repo) currently exposes older commands only (no +`+ambush+`/`+panll+` in `+--help+` output). +* PanLL integration now handles this by falling back to a local +assault-report → event-chain converter in backend +(`+src-tauri/src/main.rs+`), so import still works. + +==== 4.2 Panic-Attacker Source Build Break + +* Building current panic-attacker source fails in `+src/report/gui.rs+` +at `+eframe::run_native(...)?+` due `+eframe::Error+` conversion into +`+anyhow::Error+` (`+Send+`/`+Sync+`) constraints. +* This blocks easy validation that newly added source commands are +present in a fresh binary. + +==== 4.3 Source/Test Confidence Gap + +* PanLL now has parser/adapter tests for panic-attacker report import, +but full app-level UI automation is still missing. + +==== 4.4 Backend Stubs + +* `+src-tauri/src/main.rs:18+`: TODO Echidna validation. +* `+src-tauri/src/main.rs:31+`: TODO real vexation index tracking. +* `+src-tauri/src/main.rs:43+`: TODO feedback persistence/transport. + +''''' + +=== 5. CODE QUALITY & RISK NOTES + +* Accessibility gap: no ARIA-related attrs found in `+src/+` (roadmap +"`accessibility improvements`" still valid). +* `+rescript.json+` still uses deprecated `+"module": "es6"+` (warning +on build). +* Rust devtools setup now avoids `+unwrap()+` panic on missing window +handle. +* `+src/core/AntiCrash.res+` contains placeholder logic and TODO +integration points for real symbolic checking. + +''''' + +=== 6. COMPLETE TASK LIST (PRIORITY ORDERED) + +==== P0 - Must Fix Before Any "`Release Ready`" Claim + +* [ ] Fix panic-attacker compile failure in `+src/report/gui.rs+` so +current source can build and ship updated CLI commands. +* [ ] Validate fresh panic-attacker binary command surface (`+ambush+`, +`+panll+`) and pin compatibility expectations in PanLL docs. + +==== P1 - Core Functionality Truthfulness + +* [ ] Replace placeholder Tauri command logic with real implementations: +** `+validate_inference+` should perform real validation semantics. +** `+get_vexation_index+` should read actual signal(s), not constant +`+0.0+`. +** `+submit_feedback+` should persist/forward feedback. +* [ ] Add tests for command contracts and error paths (frontend +`+TauriCmd+` + backend command behavior). +* [ ] Add integration tests for app-level flows (Pane interactions, +event-chain import, auto-save/restore). + +==== P2 - Product Quality & Consistency + +* [ ] Update `+ROADMAP.adoc+` to mark already-shipped items done (state +persistence, keyboard shortcuts). +* [ ] Reconcile status messaging in `+README.adoc+` and +`+docs/TEA_GUIDE.md+` with actual build state. +* [ ] Decide TEA strategy: +** complete migration to official `+rescript-tea+`, or +** remove/stop signaling migration if custom TEA remains canonical. +* [ ] Replace deprecated ReScript module config (`+"es6"+` -> +`+"esmodule"+`). + +==== P3 - UX, A11y, Maintainability + +* [ ] Accessibility pass: semantic labels/roles/keyboard focus behavior +and ARIA where needed. +* [ ] Expand test coverage beyond TEA internals to component and +end-to-end behavior. +* [ ] Add performance baselines for render/update and event import +handling. + +''''' + +=== 7. THREAD DECOMPOSITION + +==== Thread A: Build Integrity + +* Keep CI compile gate green (`+res:build+`, `+deno test+`, +`+cargo check+`). +* Track/resolve new build warnings before release. + +==== Thread B: Backend Correctness + +* Implement real logic in Tauri commands. +* Expand backend tests and command-level error handling. + +==== Thread C: App-Level Testing + +* Add integration tests for key user flows. +* Extend panic-attacker import coverage from parser/backend tests to +UI-level interactions. + +==== Thread D: Docs & Truthfulness + +* Align README/ROADMAP/TEA_GUIDE with real state. +* Keep this status file updated each session. + +==== Thread E: UX/A11y + +* Accessibility audit and remediation. +* Theme/view-mode polish and consistency checks. + +''''' + +=== 8. TO-DONE (COMPLETED ITEMS) + +* [x] Custom TEA core modules implemented. +* [x] 36 Deno tests passing (TEA + panic-attacker parser tests). +* [x] Event-chain parsing and import flow wired. +* [x] ReScript compile blockers fixed (`+TauriCmd+` reserved keyword + +`+PaneW+` array slice labels). +* [x] panic-attacker integration wired (latest + selected report import, +backend conversion fallback, unit test). +* [x] panic-attacker import backend tests added (latest-file selection + +command path). +* [x] CI build gate added (`+.github/workflows/build-validation.yml+`) +for `+res:build+`, `+deno task test+`, and `+cargo check+`. +* [x] Full clean frontend rebuild validated +(`+npm run res:clean && npm run res:build+`). +* [x] localStorage persistence implemented and connected. +* [x] Keyboard shortcut subscriptions implemented. +* [x] Tauri backend command plumbing and app boot wiring in place. +* [x] BEAM API options implemented (HTTP + GraphQL + gRPC) with runtime +toggles and tests in `+beam/panll_beam+`. +* [x] Hypatia scan workflow fixed for current JSON envelope shape +(`+findings+` array under metadata object). +* [x] Added runtime stack files for Chainguard + Cerro Torre + +selur-compose orchestration. + +''''' + +=== 9. REVISION HISTORY + +* *2026-02-11:* Initial honest audit created from code + test + build +checks. + +Key correction: project is not currently 95% complete due active compile +break and backend stubs. +* *2026-02-11 (update):* panic-attacker integration implemented; +ReScript compile blockers fixed; backend fallback conversion + unit test +added. +* *2026-02-11 (update 2):* Added panic-attacker import tests, CI +build-validation workflow, validated clean ReScript rebuild, and +confirmed panic-attacker source build break (`+gui.rs+`) still blocks +fresh binary verification. +* *2026-02-11 (update 3):* Added BEAM API runtime (`+panll_beam+`) with +selectable HTTP/GraphQL/gRPC frontdoors; added BEAM tests (`+mix test+` +5/5); fixed Hypatia workflow parsing to use `+.findings+` envelope. +* *2026-02-11 (update 4):* Added `+runtime/+` stack scaffolding for +Chainguard image build, Cerro Torre pack/verify, and selur-compose +topology with `+svalinn+`, `+vordr+`, `+selur+`, `+rokur+`, and PanLL. diff --git a/docs/status/PANLL-COMPLETE-STATUS-2026-02-11.md b/docs/status/PANLL-COMPLETE-STATUS-2026-02-11.md deleted file mode 100644 index 7d0b667e..00000000 --- a/docs/status/PANLL-COMPLETE-STATUS-2026-02-11.md +++ /dev/null @@ -1,239 +0,0 @@ -# PANLL: Complete Project Status, Priority TODO Plan & Thread Decomposition -# Generated: 2026-02-11 (KEEP UPDATED EACH SESSION) -# Author: Codex (GPT-5) audit pass -# Purpose: Single source of truth for what is actually done vs what still needs work - ---- - -## HOW TO USE THIS DOCUMENT - -Read this document fully before starting new work on PanLL. -It records: -- what is genuinely working now, -- what is claimed but not yet true, -- what is currently broken, -- and the next tasks in strict priority order. - -Move completed tasks into the TO-DONE section at the bottom as work lands. - ---- - -## TABLE OF CONTENTS - -1. [Honest Status Assessment](#1-honest-status-assessment) -2. [What Is Actually Done](#2-what-is-actually-done) -3. [What Is Claimed But Not Done](#3-what-is-claimed-but-not-done) -4. [What Is Broken Right Now](#4-what-is-broken-right-now) -5. [Code Quality & Risk Notes](#5-code-quality--risk-notes) -6. [Complete Task List (Priority Ordered)](#6-complete-task-list-priority-ordered) -7. [Thread Decomposition](#7-thread-decomposition) -8. [TO-DONE (Completed Items)](#8-to-done-completed-items) -9. [Revision History](#9-revision-history) - ---- - -## 1. HONEST STATUS ASSESSMENT - -**Estimated completion: ~76% (not 95%)** - -Reasoning: -- Core TEA modules exist and have unit tests. -- Tauri backend compiles. -- Core product loop is not release-ready yet, but frontend ReScript compile now passes. -- Backend command behavior is partly placeholder logic. -- Coverage is concentrated in TEA internals, not full application behavior. - -### Reality Snapshot (2026-02-11) - -| Component | Claimed | Actual | Notes | -|-----------|---------|--------|-------| -| Custom TEA runtime | Complete | ~80% | Modules exist, tests pass, but app lifecycle/rendering is still described as partial in tests | -| Frontend ReScript build | Implied healthy | **Working** | `npm run res:build` passes (warnings only) | -| Tauri backend commands | Working | ~45% | Commands are wired, but `main.rs` still has TODO placeholder implementations | -| Event-chain import | Working | ~92% | Parser/update flow is real + panic-attacker integration path now wired | -| State persistence | Roadmap says TODO | **Implemented** | `src/Storage.res` has load/save/clear via localStorage and is wired from app init/update | -| Keyboard shortcuts | Roadmap says TODO | **Implemented (core set)** | Ctrl+Shift+L/N/B/W handlers exist in subscriptions | -| Testing | 36 tests passing | True, improving | TEA tests + panic-attacker event-chain parser tests now pass | -| Coverage | 87-91% | Misleading headline | Current run: Branch 86.2%, Line 51.4% across only TEA files under test | - ---- - -## 2. WHAT IS ACTUALLY DONE - -Verified in code and/or command execution: - -### Architecture & Core -- Custom TEA modules exist: `src/tea/Tea_Cmd.res`, `src/tea/Tea_Sub.res`, `src/tea/Tea_App.res`, `src/tea/Tea_Render.res`, `src/tea/Tea_Vdom.res`, `src/tea/Tea_Html.res`. -- Centralized model/message/update/view wiring exists: `src/Model.res`, `src/Msg.res`, `src/Update.res`, `src/View.res`, `src/App.res`. - -### Product Features Implemented -- Event-chain parse/import path implemented in `src/core/EventChain.res` and `src/components/PaneW.res`. -- File import command path implemented in `src/commands/TauriCmd.res` and update handler (`PaneW(ImportEventChainFile)` in `src/Update.res`). -- panic-attacker integration added: - - `Import latest panic-attacker` path (auto-detect latest report in panic-attacker reports dir). - - `Load panic-attacker Report` path (select report file, convert, import). - - Backend runs `panic-attack panll` when available and falls back to direct assault-report conversion when binary lacks that subcommand. -- Anti-crash flow and token gating wired (`src/core/AntiCrash.res`, `src/Update.res`). -- localStorage persistence implemented and auto-save wired (`src/Storage.res`, `src/App.res`, `src/Update.res`). -- Keyboard shortcut subscriptions implemented (`src/SubscriptionsFixed.res`). -- BEAM runtime scaffold implemented in `beam/panll_beam` with protocol-selectable API surface: - - HTTP via Bandit/Plug (`/healthz`, `/v1/status`) - - GraphQL via Absinthe (`/graphql`, `/graphiql`) - - gRPC via `panll.v1.StatusService/GetStatus` - - Runtime selection via `PANLL_BEAM_APIS` (`http`, `graphql`, `grpc`) -- Hypatia workflow parsing fixed to read scanner envelope (`.findings`) correctly for counts/severity in `.github/workflows/hypatia-scan.yml`, with explicit `FLEET_GITHUB_TOKEN` gate for cross-repo submission. -- Runtime stack scaffolding added under `runtime/`: - - Chainguard-based `Containerfile` for BEAM release - - `compose.toml` including `svalinn`, `vordr`, `selur`, `rokur`, and `panll` - - scripts for build/pack/verify via Cerro Torre and selur-compose up/down - -### Build/Test Health -- `deno task test`: **36 passed, 0 failed**. -- `deno task test:coverage`: Branch **86.2%**, Line **51.4%**, scoped to TEA files in current tests. -- `npm run res:clean && npm run res:build`: passes (warnings only). -- `cargo check` in `src-tauri`: passes (with minor unused-variable warnings). - ---- - -## 3. WHAT IS CLAIMED BUT NOT DONE - -### A) Build/Runtime Readiness Claims - -| Claim | Reality | -|------|---------| -| `v0.1.0 ... 95% complete` (`README.adoc`, `ROADMAP.adoc`) | Frontend now compiles, but release readiness is still overstated due backend stubs + thin integration coverage | -| Tauri commands "working" | Wired but logic is placeholder in `src-tauri/src/main.rs` | -| Coverage badge-level confidence | Real app line coverage is low relative to whole codebase; only selected TEA modules are covered | - -### B) Roadmap Drift (Needs Cleanup) - -Roadmap currently marks these as TODO, but code shows they are already present: -- State persistence (`src/Storage.res`) -- Keyboard shortcuts (`src/SubscriptionsFixed.res`, plus docs in `README.adoc`) - -### C) "Production Ready" Documentation Drift - -- `docs/TEA_GUIDE.md` reports `Status: Production Ready`, but: - - ReScript build passes, but production-quality integration coverage is still missing. - - Test files explicitly note missing full lifecycle/render pipeline coverage (`tests/tea_app_test.js`, `tests/tea_render_test.js`). - ---- - -## 4. WHAT IS BROKEN RIGHT NOW - -### 4.1 Panic-Attacker Binary Version Drift - -- In the original dev environment, the `panic-attack` binary (from the `panic-attacker` repo) - currently exposes older commands only (no `ambush`/`panll` in `--help` output). -- PanLL integration now handles this by falling back to a local assault-report → event-chain converter in backend (`src-tauri/src/main.rs`), so import still works. - -### 4.2 Panic-Attacker Source Build Break - -- Building current panic-attacker source fails in `src/report/gui.rs` at `eframe::run_native(...)?` due `eframe::Error` conversion into `anyhow::Error` (`Send`/`Sync`) constraints. -- This blocks easy validation that newly added source commands are present in a fresh binary. - -### 4.3 Source/Test Confidence Gap - -- PanLL now has parser/adapter tests for panic-attacker report import, but full app-level UI automation is still missing. - -### 4.4 Backend Stubs - -- `src-tauri/src/main.rs:18`: TODO Echidna validation. -- `src-tauri/src/main.rs:31`: TODO real vexation index tracking. -- `src-tauri/src/main.rs:43`: TODO feedback persistence/transport. - ---- - -## 5. CODE QUALITY & RISK NOTES - -- Accessibility gap: no ARIA-related attrs found in `src/` (roadmap "accessibility improvements" still valid). -- `rescript.json` still uses deprecated `"module": "es6"` (warning on build). -- Rust devtools setup now avoids `unwrap()` panic on missing window handle. -- `src/core/AntiCrash.res` contains placeholder logic and TODO integration points for real symbolic checking. - ---- - -## 6. COMPLETE TASK LIST (PRIORITY ORDERED) - -### P0 - Must Fix Before Any "Release Ready" Claim - -- [ ] Fix panic-attacker compile failure in `src/report/gui.rs` so current source can build and ship updated CLI commands. -- [ ] Validate fresh panic-attacker binary command surface (`ambush`, `panll`) and pin compatibility expectations in PanLL docs. - -### P1 - Core Functionality Truthfulness - -- [ ] Replace placeholder Tauri command logic with real implementations: - - `validate_inference` should perform real validation semantics. - - `get_vexation_index` should read actual signal(s), not constant `0.0`. - - `submit_feedback` should persist/forward feedback. -- [ ] Add tests for command contracts and error paths (frontend `TauriCmd` + backend command behavior). -- [ ] Add integration tests for app-level flows (Pane interactions, event-chain import, auto-save/restore). - -### P2 - Product Quality & Consistency - -- [ ] Update `ROADMAP.adoc` to mark already-shipped items done (state persistence, keyboard shortcuts). -- [ ] Reconcile status messaging in `README.adoc` and `docs/TEA_GUIDE.md` with actual build state. -- [ ] Decide TEA strategy: - - complete migration to official `rescript-tea`, or - - remove/stop signaling migration if custom TEA remains canonical. -- [ ] Replace deprecated ReScript module config (`"es6"` -> `"esmodule"`). - -### P3 - UX, A11y, Maintainability - -- [ ] Accessibility pass: semantic labels/roles/keyboard focus behavior and ARIA where needed. -- [ ] Expand test coverage beyond TEA internals to component and end-to-end behavior. -- [ ] Add performance baselines for render/update and event import handling. - ---- - -## 7. THREAD DECOMPOSITION - -### Thread A: Build Integrity -- Keep CI compile gate green (`res:build`, `deno test`, `cargo check`). -- Track/resolve new build warnings before release. - -### Thread B: Backend Correctness -- Implement real logic in Tauri commands. -- Expand backend tests and command-level error handling. - -### Thread C: App-Level Testing -- Add integration tests for key user flows. -- Extend panic-attacker import coverage from parser/backend tests to UI-level interactions. - -### Thread D: Docs & Truthfulness -- Align README/ROADMAP/TEA_GUIDE with real state. -- Keep this status file updated each session. - -### Thread E: UX/A11y -- Accessibility audit and remediation. -- Theme/view-mode polish and consistency checks. - ---- - -## 8. TO-DONE (COMPLETED ITEMS) - -- [x] Custom TEA core modules implemented. -- [x] 36 Deno tests passing (TEA + panic-attacker parser tests). -- [x] Event-chain parsing and import flow wired. -- [x] ReScript compile blockers fixed (`TauriCmd` reserved keyword + `PaneW` array slice labels). -- [x] panic-attacker integration wired (latest + selected report import, backend conversion fallback, unit test). -- [x] panic-attacker import backend tests added (latest-file selection + command path). -- [x] CI build gate added (`.github/workflows/build-validation.yml`) for `res:build`, `deno task test`, and `cargo check`. -- [x] Full clean frontend rebuild validated (`npm run res:clean && npm run res:build`). -- [x] localStorage persistence implemented and connected. -- [x] Keyboard shortcut subscriptions implemented. -- [x] Tauri backend command plumbing and app boot wiring in place. -- [x] BEAM API options implemented (HTTP + GraphQL + gRPC) with runtime toggles and tests in `beam/panll_beam`. -- [x] Hypatia scan workflow fixed for current JSON envelope shape (`findings` array under metadata object). -- [x] Added runtime stack files for Chainguard + Cerro Torre + selur-compose orchestration. - ---- - -## 9. REVISION HISTORY - -- **2026-02-11:** Initial honest audit created from code + test + build checks. - Key correction: project is not currently 95% complete due active compile break and backend stubs. -- **2026-02-11 (update):** panic-attacker integration implemented; ReScript compile blockers fixed; backend fallback conversion + unit test added. -- **2026-02-11 (update 2):** Added panic-attacker import tests, CI build-validation workflow, validated clean ReScript rebuild, and confirmed panic-attacker source build break (`gui.rs`) still blocks fresh binary verification. -- **2026-02-11 (update 3):** Added BEAM API runtime (`panll_beam`) with selectable HTTP/GraphQL/gRPC frontdoors; added BEAM tests (`mix test` 5/5); fixed Hypatia workflow parsing to use `.findings` envelope. -- **2026-02-11 (update 4):** Added `runtime/` stack scaffolding for Chainguard image build, Cerro Torre pack/verify, and selur-compose topology with `svalinn`, `vordr`, `selur`, `rokur`, and PanLL. diff --git a/docs/status/PANLL-STATUS-REPORT-2026-03-14.adoc b/docs/status/PANLL-STATUS-REPORT-2026-03-14.adoc new file mode 100644 index 00000000..a37a8c93 --- /dev/null +++ b/docs/status/PANLL-STATUS-REPORT-2026-03-14.adoc @@ -0,0 +1,548 @@ +== PanLL Comprehensive Status Report + +*Generated: 2026-03-14* *Author: Claude Opus 4.6 for Jonathan D.A. +Jewell* + +''''' + +=== Executive Summary + +PanLL is a *304K LOC, 52-panel neurosymbolic IDE* that is +architecturally complete but operationally stubbed. The UI, state +management, message routing, and test infrastructure are +production-quality (2090+ tests, 0 build errors). The gap is almost +entirely in live backend connections — every Tauri command returns mock +JSON. + +*Overall: ~95% UI-complete, ~15% operationally end-to-end.* + +''''' + +=== 1. Document TODOs & Loose Items + +==== In-Code TODOs: 59 remaining + +* Down from 90+ (28 genuinely blocked on missing backends) +* All 81 Update.res TODOs resolved (JSON deserialisation complete) +* All 3 main.rs TODOs resolved (Echidna validation, vexation tracking, +feedback persistence) + +==== Planning Documents with Outstanding Items + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Document |Location |Contents +|*docs/TODO.md* |`+panll/docs/TODO.md+` |6 TSDM-scored sprints, 60+ +items, ~40% still open + +|*ROADMAP.adoc* |`+panll/ROADMAP.adoc+` |v0.1.0→v1.0.0 milestones (412 +lines) + +|*STATE.scm* |`+panll/.machine_readable/STATE.scm+` |3 +critical-next-actions, 5% gap analysis + +|*WORKSPACE-LAYER-PROGRESS.md* |`+panll/.machine_readable/+` |Skeleton +done, flesh-out pending + +|*CHANGELOG.md* |`+panll/CHANGELOG.md+` |34 entries, latest 2026-03-14 +|=== + +==== docs/TODO.md Sprint Status + +[cols=",,",options="header",] +|=== +|Sprint |Theme |Status +|1. "`Make It Breathe`" |Core panels alive |Mostly done +|2. "`Make It Real`" |Backend connections |Partially done +|3. "`Make It Complete`" |Test coverage |Mostly done +|4. "`Make It Extensible`" |Clade system |Mostly done +|5. "`Code MRI`" |Corrective maintenance |Partially done +|6. "`Dogfood Mode`" |CRG promotion |Barely started +|=== + +==== Infrastructure Debt (from TODO.md) + +* TOPOLOGY.md sync +* STATE.scm updates +* Float deprecation fixes +* 6 total items + +''''' + +=== 2. Roadmap Status + +[width="100%",cols="25%,17%,17%,41%",options="header",] +|=== +|Milestone |Target |Status |Key Missing Pieces +|*v0.1.0* |2026-02-28 |*92%* |CRG D→C promotion (needs dogfooding) + +|*v0.2.0* (MVP) |TBD |*~30%* |Real VeriSimDB persistence, real +reposystem connection, real BoJ backend wiring + +|*v0.3.0* |TBD |*~15%* |ECHIDNA live proving, proven library +integration, neurosymbolic core + +|*v0.4.0* |TBD |*~5%* |Stapeln containers for backends, Eclexia, full +multi-agent + +|*v0.5.0* |TBD |*~0%* |Pane Studio scaffolder, dev workflows + +|*v1.0.0* |TBD |*~0%* |Security audit, stable API, production hardening +|=== + +*The v0.2.0 gap is the biggest blocker* — everything is wired with +mock/stub backends but almost nothing talks to live services yet. + +''''' + +=== 3. TypeLL Integration Completeness + +==== What’s Done (100% UI coverage) + +* All 52 panels fire `+TypeCheckResult+` +* `+TypeLLService.res+` cross-cutting helpers available to any panel +* Progressive disclosure (4 view layers: Raw → Folded → Glyphed → +WYSIWYG) +* Kernel: 221 tests, 0 failures, 5 resolved kernel gaps +* `+panelTypeChecks+` Dict tracks type checking state per panel +* Graceful degradation — TypeLL errors don’t block panel workflows + +==== What Remains + +[width="100%",cols="27%,34%,39%",options="header",] +|=== +|Item |Status |Blocker +|Runtime type checking (all panels) |*Done* |— + +|TypeLLService cross-cutting helpers |*Done* |— + +|Progressive disclosure (4 view layers) |*Done* |— + +|Compile-time checking via ReScript PPX |*Not started* |Needs custom +build plugin, long-term + +|TypeLL kernel as real dependency (not stubs) |*Not wired* |Need to +connect to actual TypeLL binary/service + +|Idris2 ABI proof verification at runtime |*Not wired* |Need Idris2→Zig +FFI pipeline +|=== + +*Assessment:* TypeLL is architecturally complete but operationally +stubbed. UI and message routing are all there, but Tauri commands return +mock data. + +''''' + +=== 4. Major Incomplete Core Elements + +[width="100%",cols="28%,32%,40%",options="header",] +|=== +|Subsystem |Completeness |What’s Missing +|*Contractiles* |*20%* |Only 1 Nickel file (safedom-enforcement.ncl). k9 +dir empty. Must/trust/dust/lust stubs only. + +|*ObservatoryEngine* |*75%* |ObservabilityEngine solid (275 lines) but +ObservatoryEngine is 52-line stub + +|*Live backend connections* |*~5%* |Every panel has Tauri command stubs +but almost none connect to real services + +|*CRG promotion* |*0%* |Cannot be automated — requires real dogfooding + +|*Pane Studio* (scaffolder v2) |*0%* |Minter exists for basic +scaffolding, full "`Pane Studio`" from v0.5.0 doesn’t + +|*robot-repo-automaton* |*5%* |The executor bot barely exists + +|*cipherbot / accessibilitybot* |*Nascent* |Defined but not +substantially implemented + +|*eNSAID as independent spec* |*0%* |Spec still lives inside PanLL, not +its own repo +|=== + +==== Subsystem Completeness Matrix + +[width="100%",cols="30%,34%,18%,18%",options="header",] +|=== +|Subsystem |Completeness |Lines |Notes +|Core Panels (L/N/W) |*100%* |4,133 |PaneN and PaneW 1.9K each + +|TEA Framework |*100%* |3,959 |18 modules, production-ready + +|SafeDOM |*100%* |724+ |4-layer defence-in-depth + 75 tests + +|Workspace Management |*100%* |1,490 |Full MVC pattern + +|BoJ Integration |*100%* |1,854 |Full CRUD + Tauri dispatch + +|Accessibility |*100%* |882 |ARIA, keyboard nav, toolbar + +|Help System |*100%* |1,485 |Context-sensitive, searchable + +|Tiling/Multi-monitor |*100%* |411 |WindowBridge + BroadcastChannel + +|Panel Clades |*95%* |44 clades, 55 manifests |Some clades lack +individual .a2ml + +|Rust Backend |*100%* |19,857 |39 modules, all with types.rs + +commands.rs + +|Test Suite |*100%* |19,648 |98 test files, 2090+ tests + +|Build/CI |*100%* |17 workflows |All SHA-pinned, operational + +|Observability |*75%* |555 |ObservatoryEngine minimal + +|Contractiles |*20%* |~100 |Only SafeDOM enforcement +|=== + +''''' + +=== 5. eNSAID Vision Gap Analysis + +The eNSAID spec (DD-001) defines PanLL as the reference implementation. +Here’s how close we are: + +[width="99%",cols="43%,20%,27%,10%",options="header",] +|=== +|eNSAID Requirement |UI Done? |Operational? |Gap +|Binary Star architecture (human-machine co-orbit) |Yes |No |No real +ML/AI agent connected + +|Three-pane model (L/N/W) |Yes |Partial |Pane-N has no real neural +stream + +|Anti-Crash Gate (circuit breaker N→W) |Yes |Mock |Validates against +mock constraints + +|Vexometer (cognitive friction) |Yes |Partial |Tracks UI interactions, +no backend ML + +|Orbital Sync (cross-pane drift) |Yes |Yes |Hash-based, working + +|Information Humidity (adaptive density) |Yes |Yes |Working + +|Contractiles (elastic state contracts) |Partial |No |20% complete + +|ECHIDNA theorem prover integration |Yes |No |No live prover connection + +|VeriSimDB persistence |Yes |No |No live database + +|Multi-agent orchestration (7-Tentacles) |Yes |No |No real agent +dispatch + +|Code Provenance (DD-006) |Yes |No |No git blame wiring + +|Cognitive Governance Stack (DD-007) |Yes |Partial |Vexometer works, +others mock + +|Panel Clades (DD-010) |Yes |Yes |Working, 44 clades + +|Code MRI (DD-016) |Yes |Partial |VoiceTag (L0), Blake3 provenance (L1), +Timeline engine (L2) built; TimelineCmd + TimelineModel + dashboard +wiring added 2026-03-21 + +|Care-On/Eco-Mode (DD-017) |No |No |Not started + +|Dogfood Mode (DD-018) |No |No |Not started + +|eNSAID as independent spec |Yes |Yes |Separated to ensaid-spec repo; +PanLL retains implementation code (EnsaidConfigEngine, EnsaidConfigCmd) +|=== + +*Honest assessment: ~60% of the eNSAID vision is implemented at UI +level, ~15% is operational end-to-end.* + +''''' + +=== 6. The Multicolour Agent Family + +==== 11 Core Bots Across 4 Tiers + +[width="100%",cols="17%,13%,21%,15%,34%",options="header",] +|=== +|Tier |Bot |Colour |Role |Completeness +|*0 (Engine)* |hypatia |Deep Purple |Neurosymbolic CI/CD coordinator +|70% + +|*1 (Verifier)* |rhodibot |Metallic Silver |RSR structural compliance +|50% + +|*1 (Verifier)* |echidnabot |Indigo/Cyan |Formal verification + fuzzing +|75% + +|*1 (Verifier)* |sustainabot |Green |Ecological/economic analysis |25% + +|*1 (Verifier)* |panicbot |Red |Static analysis (wraps panic-attack) +|New + +|*2 (Finisher)* |glambot |Gold |Presentation quality, WCAG, SEO |60% + +|*2 (Finisher)* |seambot |Orange/Amber |Seam integrity, drift detection +|55% + +|*2 (Finisher)* |finishbot |Purple |Release readiness gate |65% + +|*2 (Finisher)* |accessibilitybot |Blue |Deep WCAG 2.3 AAA |Nascent + +|*3 (Specialist)* |cipherbot |Purple |Crypto hygiene, post-quantum +|Nascent + +|*4 (Executor)* |robot-repo-automaton |— |Applies approved fixes |5% +|=== + +==== Execution Hierarchy + +.... +Tier 0: ENGINE + └── hypatia (coordinates everything) + ▼ +Tier 1: VERIFIERS (produce findings, run parallel) + ├── rhodibot (no deps) + ├── echidnabot (no deps) + ├── sustainabot (no deps) + └── panicbot (depends: rhodibot) + ▼ verifiers_complete() gate +Tier 2: FINISHERS (consume findings, run sequentially) + ├── glambot (depends: rhodibot) + ├── seambot (depends: rhodibot, echidnabot) + ├── finishbot (depends: rhodibot, glambot) + ├── accessibilitybot (depends: rhodibot, glambot) + └── cipherbot (depends: rhodibot, echidnabot) + ▼ +Tier 3: EXECUTOR + └── robot-repo-automaton (applies approved fixes) +.... + +==== Safety Triangle (gates all automated actions) + +* *Eliminate* (≥0.95 confidence) → Direct fix, no review +* *Substitute* (≥0.85 confidence) → Proven module replacement, needs +review +* *Control* (<0.85 confidence) → Human review required + +''''' + +=== 7. Bot-Assisted Panel Lifecycle (THE GAP) + +==== What Exists Now + +* *Minter panel* — generates ReScript skeleton +(Model/Engine/Cmd/Component) +* *Provisioner panel* — manages isolation tiers and portfolios +* *NO bot integration with either* — minting and provisioning are fully +manual + +==== What We Need to Build + +[width="100%",cols="42%,20%,38%",options="header",] +|=== +|Lifecycle Phase |Bot(s) |What They’d Do +|*Minting* (scaffold) |glambot + rhodibot |Validate naming, generate +A2ML clade manifest, ensure RSR structure, create bot_directives + +|*Provisioning* (configure) |seambot + finishbot |Verify panel +seams/contracts, check isolation tier, validate deps + +|*Configuring* (integrate) |echidnabot + seambot |Type-check panel +interfaces, verify BoJ routing config, validate Msg/Update wiring + +|*Wiring* (connect) |finishbot + rhodibot |Gate: all 8 files present, +tests passing, clade registered, registry entry, Update.res routing +|=== + +==== Concrete Deliverables Needed + +[arabic] +. *`+panel-directives.scm+`* — Per-panel bot rules (what each bot checks +for each panel) +. *`+minting-checklist.scm+`* — Pre-mint validation pipeline definition +. *Panel-specific bot handlers* in gitbot-fleet (extend shared-context +with panel awareness) +. *Minter → fleet integration* — Minter calls fleet bots after +generating skeleton +. *Provisioner → fleet integration* — Provisioner asks finishbot before +activating panel +. *`+panel-branding.scm+`* — Visual identity per panel family (formalise +colour registry) + +''''' + +=== 8. Existing Panel Inventory (52 Panels) + +==== Core (3) + +Panel-L (Symbolic Mass), Panel-N (Neural Stream), Panel-W +(World/Barycentre) + +==== Overlay Panels (14) + +CloudGuard, VAB, Farm, Fleet, Hypatia, Reposystem, Aerie, Interfaces, +Playgrounds, Palimpsest Plaza, Minter, Protocol-Squisher, My-Lang, BoJ + +==== IDApTIK eNSAID (11) + +Valence Shell, Game Preview, VM Inspector, Network Topology, Level +Architect, Coprocessors, Multiplayer Monitor, DLC Workshop, Editor +Bridge, Build Dashboard, Release Manager + +==== Cross-Cutting Services (4) + +TypeLL, 7-Tentacles, A2ML/K9, Coprocessor Engine + +==== Infrastructure (5) + +Panel Switcher, Provisioner, Code Provenance, Filesystem Watcher, Clade +Browser + +==== Cognitive Governance (6) + +Vexometer, Anti-Crash Gate, Orbital Drift Aura, Feedback-O-Tron, +Information Humidity, Dark Start + +==== Utility (9+) + +Databases, AI, Repo Loader, Workspace, Capture, Security, Migration, +panic-attack, Mass Panic, TSDM, Automation Router, Observability, Umoja, +UMS + +''''' + +=== 9. Checkpoint File Summary (.machine_readable/) + +[width="100%",cols="18%,17%,37%,28%",options="header",] +|=== +|File |Size |Last Updated |Contents +|STATE.scm |34.9 KB |2026-03-10 |95% completion, 361 source files, 8 +session histories + +|META.scm |14.4 KB |— |7 ADRs, dev practices, cross-cutting concerns + +|ECOSYSTEM.scm |14.2 KB |2026-03-14 |16 related projects, TypeLL + BoJ +deps + +|AGENTIC.scm |8.9 KB |— |Agent interaction patterns, multi-agent +coordination + +|NEUROSYM.scm |8.4 KB |— |Symbolic/neural/integration layers + +|PLAYBOOK.scm |12.9 KB |— |SOPs, workflows, automation patterns + +|SECURITY.scm |2.5 KB |— |Security policy +|=== + +''''' + +=== 10. Design Documents (for reference) + +[width="100%",cols="38%,37%,25%",options="header",] +|=== +|Document |Location |Topic +|DESIGN-DECISIONS.md |docs/ |18 DDs (DD-001 to DD-018), all accepted + +|DESIGN-2026-02-28-echidna-proof-ux.md |docs/design/ |Proof +visualisation UX + +|DESIGN-2026-02-28-discipline-layouts.md |docs/design/ |Layout +discipline system + +|DESIGN-2026-02-28-collaboration.md |docs/design/ |Human-Machine +collaboration patterns + +|DESIGN-2026-02-28-slm-heutagogy.md |docs/design/ |Small language model +pedagogy + +|DESIGN-2026-02-28-infrastructure-requirements.md |docs/design/ +|Infrastructure requirements + +|DESIGN-2026-02-28-strategic-assessment.md |docs/design/ |Strategic +assessment + +|DESIGN-2026-03-01-vab-panel.md |docs/design/ |VAB (Verified Assembly +Building) panel + +|DESIGN-2026-03-08-idaptik-ensaid.md |docs/design/ |IDApTIK game +development environment + +|TEA_GUIDE.md |root |Custom TEA runtime documentation + +|ARCHITECTURE.txt |root |Full architecture overview (10.9 KB) + +|ARCHITECTURE.md |root |Simplified architecture doc + +|PANEL-INVENTORY.md |root |Catalog of panels across 6 categories + +|TAURI-COMMANDS.md |root |All Rust backend commands + +|TESTING.md |root |Test infrastructure and coverage +|=== + +''''' + +=== 11. Source Code Statistics + +* *Total lines:* 304,497 LOC +* *Total files:* 1,186 source files +* *ReScript:* 258 files (frontend) +* *Rust:* 103 files (backend/Tauri, 39 modules) +* *JavaScript tests:* 98 files (19,648 lines) +* *Build status:* 0 errors, 7 warnings (unused vars) +* *Tests:* 2,090+ (1,879 Deno + 211 Rust) + +''''' + +=== 12. Strategic Priorities + +==== Priority 1: v0.2.0 — Make It Real + +Connect 3-4 panels to live backends (BoJ, VeriSimDB, ECHIDNA) to prove +the architecture works end-to-end. This is the difference between a demo +and an MVP. + +==== Priority 2: Bot-Assisted Panel Lifecycle + +Wire the fleet into minting/provisioning so new panels get validated +automatically. Highest leverage — makes every future panel creation +faster and more reliable. + +==== Priority 3: Contractiles + +The 20% completeness is a risk. Contractiles are load-bearing for the +Cognitive Governance Stack (DD-007). The k9 directory being empty means +the security enforcement layer has no teeth. + +==== Priority 4: eNSAID Separation + +Extract the eNSAID spec into its own repo (DD-001’s V for Vendetta +Principle). Currently the spec and implementation are entangled. + +==== Priority 5: Code MRI (DD-016) + +VoiceTag, Blake3 provenance, VeriSimDB timeline — none built yet. This +is a differentiator. + +''''' + +=== 13. The 5% Gap (95% → 100% for v0.1.0) + +[width="100%",cols="22%,46%,32%",options="header",] +|=== +|Item |Completeness |Blocker +|CRG D→C promotion |0% |Requires author dogfooding (cannot automate) + +|Benchmark tests |60% |Need more performance baselines + +|Integration tests |80% |Need cross-panel integration scenarios + +|SeamEngine |80% |Need remaining compliance seam definitions + +|3 flaky Rust tests |— |Race conditions in multiplayer_monitor, +valence_shell +|=== + +''''' + +_This document is a point-in-time snapshot. For live state, check +`+panll/.machine_readable/STATE.scm+`._ diff --git a/docs/status/PANLL-STATUS-REPORT-2026-03-14.md b/docs/status/PANLL-STATUS-REPORT-2026-03-14.md deleted file mode 100644 index c8ea1311..00000000 --- a/docs/status/PANLL-STATUS-REPORT-2026-03-14.md +++ /dev/null @@ -1,332 +0,0 @@ -# PanLL Comprehensive Status Report -**Generated: 2026-03-14** -**Author: Claude Opus 4.6 for Jonathan D.A. Jewell** - ---- - -## Executive Summary - -PanLL is a **304K LOC, 52-panel neurosymbolic IDE** that is architecturally complete but operationally stubbed. The UI, state management, message routing, and test infrastructure are production-quality (2090+ tests, 0 build errors). The gap is almost entirely in live backend connections — every Tauri command returns mock JSON. - -**Overall: ~95% UI-complete, ~15% operationally end-to-end.** - ---- - -## 1. Document TODOs & Loose Items - -### In-Code TODOs: 59 remaining -- Down from 90+ (28 genuinely blocked on missing backends) -- All 81 Update.res TODOs resolved (JSON deserialisation complete) -- All 3 main.rs TODOs resolved (Echidna validation, vexation tracking, feedback persistence) - -### Planning Documents with Outstanding Items - -| Document | Location | Contents | -|----------|----------|----------| -| **docs/TODO.md** | `panll/docs/TODO.md` | 6 TSDM-scored sprints, 60+ items, ~40% still open | -| **ROADMAP.adoc** | `panll/ROADMAP.adoc` | v0.1.0→v1.0.0 milestones (412 lines) | -| **STATE.scm** | `panll/.machine_readable/STATE.scm` | 3 critical-next-actions, 5% gap analysis | -| **WORKSPACE-LAYER-PROGRESS.md** | `panll/.machine_readable/` | Skeleton done, flesh-out pending | -| **CHANGELOG.md** | `panll/CHANGELOG.md` | 34 entries, latest 2026-03-14 | - -### docs/TODO.md Sprint Status - -| Sprint | Theme | Status | -|--------|-------|--------| -| 1. "Make It Breathe" | Core panels alive | Mostly done | -| 2. "Make It Real" | Backend connections | Partially done | -| 3. "Make It Complete" | Test coverage | Mostly done | -| 4. "Make It Extensible" | Clade system | Mostly done | -| 5. "Code MRI" | Corrective maintenance | Partially done | -| 6. "Dogfood Mode" | CRG promotion | Barely started | - -### Infrastructure Debt (from TODO.md) -- TOPOLOGY.md sync -- STATE.scm updates -- Float deprecation fixes -- 6 total items - ---- - -## 2. Roadmap Status - -| Milestone | Target | Status | Key Missing Pieces | -|-----------|--------|--------|-------------------| -| **v0.1.0** | 2026-02-28 | **92%** | CRG D→C promotion (needs dogfooding) | -| **v0.2.0** (MVP) | TBD | **~30%** | Real VeriSimDB persistence, real reposystem connection, real BoJ backend wiring | -| **v0.3.0** | TBD | **~15%** | ECHIDNA live proving, proven library integration, neurosymbolic core | -| **v0.4.0** | TBD | **~5%** | Stapeln containers for backends, Eclexia, full multi-agent | -| **v0.5.0** | TBD | **~0%** | Pane Studio scaffolder, dev workflows | -| **v1.0.0** | TBD | **~0%** | Security audit, stable API, production hardening | - -**The v0.2.0 gap is the biggest blocker** — everything is wired with mock/stub backends but almost nothing talks to live services yet. - ---- - -## 3. TypeLL Integration Completeness - -### What's Done (100% UI coverage) -- All 52 panels fire `TypeCheckResult` -- `TypeLLService.res` cross-cutting helpers available to any panel -- Progressive disclosure (4 view layers: Raw → Folded → Glyphed → WYSIWYG) -- Kernel: 221 tests, 0 failures, 5 resolved kernel gaps -- `panelTypeChecks` Dict tracks type checking state per panel -- Graceful degradation — TypeLL errors don't block panel workflows - -### What Remains - -| Item | Status | Blocker | -|------|--------|---------| -| Runtime type checking (all panels) | **Done** | — | -| TypeLLService cross-cutting helpers | **Done** | — | -| Progressive disclosure (4 view layers) | **Done** | — | -| Compile-time checking via ReScript PPX | **Not started** | Needs custom build plugin, long-term | -| TypeLL kernel as real dependency (not stubs) | **Not wired** | Need to connect to actual TypeLL binary/service | -| Idris2 ABI proof verification at runtime | **Not wired** | Need Idris2→Zig FFI pipeline | - -**Assessment:** TypeLL is architecturally complete but operationally stubbed. UI and message routing are all there, but Tauri commands return mock data. - ---- - -## 4. Major Incomplete Core Elements - -| Subsystem | Completeness | What's Missing | -|-----------|-------------|----------------| -| **Contractiles** | **20%** | Only 1 Nickel file (safedom-enforcement.ncl). k9 dir empty. Must/trust/dust/lust stubs only. | -| **ObservatoryEngine** | **75%** | ObservabilityEngine solid (275 lines) but ObservatoryEngine is 52-line stub | -| **Live backend connections** | **~5%** | Every panel has Tauri command stubs but almost none connect to real services | -| **CRG promotion** | **0%** | Cannot be automated — requires real dogfooding | -| **Pane Studio** (scaffolder v2) | **0%** | Minter exists for basic scaffolding, full "Pane Studio" from v0.5.0 doesn't | -| **robot-repo-automaton** | **5%** | The executor bot barely exists | -| **cipherbot / accessibilitybot** | **Nascent** | Defined but not substantially implemented | -| **eNSAID as independent spec** | **0%** | Spec still lives inside PanLL, not its own repo | - -### Subsystem Completeness Matrix - -| Subsystem | Completeness | Lines | Notes | -|-----------|-------------|-------|-------| -| Core Panels (L/N/W) | **100%** | 4,133 | PaneN and PaneW 1.9K each | -| TEA Framework | **100%** | 3,959 | 18 modules, production-ready | -| SafeDOM | **100%** | 724+ | 4-layer defence-in-depth + 75 tests | -| Workspace Management | **100%** | 1,490 | Full MVC pattern | -| BoJ Integration | **100%** | 1,854 | Full CRUD + Tauri dispatch | -| Accessibility | **100%** | 882 | ARIA, keyboard nav, toolbar | -| Help System | **100%** | 1,485 | Context-sensitive, searchable | -| Tiling/Multi-monitor | **100%** | 411 | WindowBridge + BroadcastChannel | -| Panel Clades | **95%** | 44 clades, 55 manifests | Some clades lack individual .a2ml | -| Rust Backend | **100%** | 19,857 | 39 modules, all with types.rs + commands.rs | -| Test Suite | **100%** | 19,648 | 98 test files, 2090+ tests | -| Build/CI | **100%** | 17 workflows | All SHA-pinned, operational | -| Observability | **75%** | 555 | ObservatoryEngine minimal | -| Contractiles | **20%** | ~100 | Only SafeDOM enforcement | - ---- - -## 5. eNSAID Vision Gap Analysis - -The eNSAID spec (DD-001) defines PanLL as the reference implementation. Here's how close we are: - -| eNSAID Requirement | UI Done? | Operational? | Gap | -|--------------------|----------|-------------|-----| -| Binary Star architecture (human-machine co-orbit) | Yes | No | No real ML/AI agent connected | -| Three-pane model (L/N/W) | Yes | Partial | Pane-N has no real neural stream | -| Anti-Crash Gate (circuit breaker N→W) | Yes | Mock | Validates against mock constraints | -| Vexometer (cognitive friction) | Yes | Partial | Tracks UI interactions, no backend ML | -| Orbital Sync (cross-pane drift) | Yes | Yes | Hash-based, working | -| Information Humidity (adaptive density) | Yes | Yes | Working | -| Contractiles (elastic state contracts) | Partial | No | 20% complete | -| ECHIDNA theorem prover integration | Yes | No | No live prover connection | -| VeriSimDB persistence | Yes | No | No live database | -| Multi-agent orchestration (7-Tentacles) | Yes | No | No real agent dispatch | -| Code Provenance (DD-006) | Yes | No | No git blame wiring | -| Cognitive Governance Stack (DD-007) | Yes | Partial | Vexometer works, others mock | -| Panel Clades (DD-010) | Yes | Yes | Working, 44 clades | -| Code MRI (DD-016) | Yes | Partial | VoiceTag (L0), Blake3 provenance (L1), Timeline engine (L2) built; TimelineCmd + TimelineModel + dashboard wiring added 2026-03-21 | -| Care-On/Eco-Mode (DD-017) | No | No | Not started | -| Dogfood Mode (DD-018) | No | No | Not started | -| eNSAID as independent spec | Yes | Yes | Separated to ensaid-spec repo; PanLL retains implementation code (EnsaidConfigEngine, EnsaidConfigCmd) | - -**Honest assessment: ~60% of the eNSAID vision is implemented at UI level, ~15% is operational end-to-end.** - ---- - -## 6. The Multicolour Agent Family - -### 11 Core Bots Across 4 Tiers - -| Tier | Bot | Colour | Role | Completeness | -|------|-----|--------|------|-------------| -| **0 (Engine)** | hypatia | Deep Purple | Neurosymbolic CI/CD coordinator | 70% | -| **1 (Verifier)** | rhodibot | Metallic Silver | RSR structural compliance | 50% | -| **1 (Verifier)** | echidnabot | Indigo/Cyan | Formal verification + fuzzing | 75% | -| **1 (Verifier)** | sustainabot | Green | Ecological/economic analysis | 25% | -| **1 (Verifier)** | panicbot | Red | Static analysis (wraps panic-attack) | New | -| **2 (Finisher)** | glambot | Gold | Presentation quality, WCAG, SEO | 60% | -| **2 (Finisher)** | seambot | Orange/Amber | Seam integrity, drift detection | 55% | -| **2 (Finisher)** | finishbot | Purple | Release readiness gate | 65% | -| **2 (Finisher)** | accessibilitybot | Blue | Deep WCAG 2.3 AAA | Nascent | -| **3 (Specialist)** | cipherbot | Purple | Crypto hygiene, post-quantum | Nascent | -| **4 (Executor)** | robot-repo-automaton | — | Applies approved fixes | 5% | - -### Execution Hierarchy - -``` -Tier 0: ENGINE - └── hypatia (coordinates everything) - ▼ -Tier 1: VERIFIERS (produce findings, run parallel) - ├── rhodibot (no deps) - ├── echidnabot (no deps) - ├── sustainabot (no deps) - └── panicbot (depends: rhodibot) - ▼ verifiers_complete() gate -Tier 2: FINISHERS (consume findings, run sequentially) - ├── glambot (depends: rhodibot) - ├── seambot (depends: rhodibot, echidnabot) - ├── finishbot (depends: rhodibot, glambot) - ├── accessibilitybot (depends: rhodibot, glambot) - └── cipherbot (depends: rhodibot, echidnabot) - ▼ -Tier 3: EXECUTOR - └── robot-repo-automaton (applies approved fixes) -``` - -### Safety Triangle (gates all automated actions) -- **Eliminate** (≥0.95 confidence) → Direct fix, no review -- **Substitute** (≥0.85 confidence) → Proven module replacement, needs review -- **Control** (<0.85 confidence) → Human review required - ---- - -## 7. Bot-Assisted Panel Lifecycle (THE GAP) - -### What Exists Now -- **Minter panel** — generates ReScript skeleton (Model/Engine/Cmd/Component) -- **Provisioner panel** — manages isolation tiers and portfolios -- **NO bot integration with either** — minting and provisioning are fully manual - -### What We Need to Build - -| Lifecycle Phase | Bot(s) | What They'd Do | -|----------------|--------|---------------| -| **Minting** (scaffold) | glambot + rhodibot | Validate naming, generate A2ML clade manifest, ensure RSR structure, create bot_directives | -| **Provisioning** (configure) | seambot + finishbot | Verify panel seams/contracts, check isolation tier, validate deps | -| **Configuring** (integrate) | echidnabot + seambot | Type-check panel interfaces, verify BoJ routing config, validate Msg/Update wiring | -| **Wiring** (connect) | finishbot + rhodibot | Gate: all 8 files present, tests passing, clade registered, registry entry, Update.res routing | - -### Concrete Deliverables Needed - -1. **`panel-directives.scm`** — Per-panel bot rules (what each bot checks for each panel) -2. **`minting-checklist.scm`** — Pre-mint validation pipeline definition -3. **Panel-specific bot handlers** in gitbot-fleet (extend shared-context with panel awareness) -4. **Minter → fleet integration** — Minter calls fleet bots after generating skeleton -5. **Provisioner → fleet integration** — Provisioner asks finishbot before activating panel -6. **`panel-branding.scm`** — Visual identity per panel family (formalise colour registry) - ---- - -## 8. Existing Panel Inventory (52 Panels) - -### Core (3) -Panel-L (Symbolic Mass), Panel-N (Neural Stream), Panel-W (World/Barycentre) - -### Overlay Panels (14) -CloudGuard, VAB, Farm, Fleet, Hypatia, Reposystem, Aerie, Interfaces, Playgrounds, Palimpsest Plaza, Minter, Protocol-Squisher, My-Lang, BoJ - -### IDApTIK eNSAID (11) -Valence Shell, Game Preview, VM Inspector, Network Topology, Level Architect, Coprocessors, Multiplayer Monitor, DLC Workshop, Editor Bridge, Build Dashboard, Release Manager - -### Cross-Cutting Services (4) -TypeLL, 7-Tentacles, A2ML/K9, Coprocessor Engine - -### Infrastructure (5) -Panel Switcher, Provisioner, Code Provenance, Filesystem Watcher, Clade Browser - -### Cognitive Governance (6) -Vexometer, Anti-Crash Gate, Orbital Drift Aura, Feedback-O-Tron, Information Humidity, Dark Start - -### Utility (9+) -Databases, AI, Repo Loader, Workspace, Capture, Security, Migration, panic-attack, Mass Panic, TSDM, Automation Router, Observability, Umoja, UMS - ---- - -## 9. Checkpoint File Summary (.machine_readable/) - -| File | Size | Last Updated | Contents | -|------|------|-------------|----------| -| STATE.scm | 34.9 KB | 2026-03-10 | 95% completion, 361 source files, 8 session histories | -| META.scm | 14.4 KB | — | 7 ADRs, dev practices, cross-cutting concerns | -| ECOSYSTEM.scm | 14.2 KB | 2026-03-14 | 16 related projects, TypeLL + BoJ deps | -| AGENTIC.scm | 8.9 KB | — | Agent interaction patterns, multi-agent coordination | -| NEUROSYM.scm | 8.4 KB | — | Symbolic/neural/integration layers | -| PLAYBOOK.scm | 12.9 KB | — | SOPs, workflows, automation patterns | -| SECURITY.scm | 2.5 KB | — | Security policy | - ---- - -## 10. Design Documents (for reference) - -| Document | Location | Topic | -|----------|----------|-------| -| DESIGN-DECISIONS.md | docs/ | 18 DDs (DD-001 to DD-018), all accepted | -| DESIGN-2026-02-28-echidna-proof-ux.md | docs/design/ | Proof visualisation UX | -| DESIGN-2026-02-28-discipline-layouts.md | docs/design/ | Layout discipline system | -| DESIGN-2026-02-28-collaboration.md | docs/design/ | Human-Machine collaboration patterns | -| DESIGN-2026-02-28-slm-heutagogy.md | docs/design/ | Small language model pedagogy | -| DESIGN-2026-02-28-infrastructure-requirements.md | docs/design/ | Infrastructure requirements | -| DESIGN-2026-02-28-strategic-assessment.md | docs/design/ | Strategic assessment | -| DESIGN-2026-03-01-vab-panel.md | docs/design/ | VAB (Verified Assembly Building) panel | -| DESIGN-2026-03-08-idaptik-ensaid.md | docs/design/ | IDApTIK game development environment | -| TEA_GUIDE.md | root | Custom TEA runtime documentation | -| ARCHITECTURE.txt | root | Full architecture overview (10.9 KB) | -| ARCHITECTURE.md | root | Simplified architecture doc | -| PANEL-INVENTORY.md | root | Catalog of panels across 6 categories | -| TAURI-COMMANDS.md | root | All Rust backend commands | -| TESTING.md | root | Test infrastructure and coverage | - ---- - -## 11. Source Code Statistics - -- **Total lines:** 304,497 LOC -- **Total files:** 1,186 source files -- **ReScript:** 258 files (frontend) -- **Rust:** 103 files (backend/Tauri, 39 modules) -- **JavaScript tests:** 98 files (19,648 lines) -- **Build status:** 0 errors, 7 warnings (unused vars) -- **Tests:** 2,090+ (1,879 Deno + 211 Rust) - ---- - -## 12. Strategic Priorities - -### Priority 1: v0.2.0 — Make It Real -Connect 3-4 panels to live backends (BoJ, VeriSimDB, ECHIDNA) to prove the architecture works end-to-end. This is the difference between a demo and an MVP. - -### Priority 2: Bot-Assisted Panel Lifecycle -Wire the fleet into minting/provisioning so new panels get validated automatically. Highest leverage — makes every future panel creation faster and more reliable. - -### Priority 3: Contractiles -The 20% completeness is a risk. Contractiles are load-bearing for the Cognitive Governance Stack (DD-007). The k9 directory being empty means the security enforcement layer has no teeth. - -### Priority 4: eNSAID Separation -Extract the eNSAID spec into its own repo (DD-001's V for Vendetta Principle). Currently the spec and implementation are entangled. - -### Priority 5: Code MRI (DD-016) -VoiceTag, Blake3 provenance, VeriSimDB timeline — none built yet. This is a differentiator. - ---- - -## 13. The 5% Gap (95% → 100% for v0.1.0) - -| Item | Completeness | Blocker | -|------|-------------|---------| -| CRG D→C promotion | 0% | Requires author dogfooding (cannot automate) | -| Benchmark tests | 60% | Need more performance baselines | -| Integration tests | 80% | Need cross-panel integration scenarios | -| SeamEngine | 80% | Need remaining compliance seam definitions | -| 3 flaky Rust tests | — | Race conditions in multiplayer_monitor, valence_shell | - ---- - -*This document is a point-in-time snapshot. For live state, check `panll/.machine_readable/STATE.scm`.* diff --git a/docs/status/panll-features-build.adoc b/docs/status/panll-features-build.adoc new file mode 100644 index 00000000..43bc34c3 --- /dev/null +++ b/docs/status/panll-features-build.adoc @@ -0,0 +1,721 @@ +== PanLL Feature Build Script — Ordered Smallest → Largest + +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== + +== INSTRUCTIONS: Copy everything below the line into Claude Code as a single message. + +== Claude will build each feature in order, asking questions where needed. + +== Each phase completes and compiles before moving to the next. + +== + +== PREREQUISITES: PanLL must already be cloned and building. + +== cd ~/Documents/hyperpolymath-repos/panll + +== just build + +== ───────────────────────────────────────────────────────────────────── + +I want you to build these PanLL features IN ORDER from smallest to +largest. Before you start, read the AI manifest: + +.... +cat 0-AI-MANIFEST.a2ml +.... + +Then read the architecture: + +.... +cat ARCHITECTURE.txt +cat TOPOLOGY.md +.... + +Then read the existing model, view, and update files to understand the +TEA pattern: + +.... +cat src/Model.res +cat src/View.res +cat src/Update.res (first 200 lines) +.... + +PanLL uses: - *ReScript* (frontend, TEA pattern — Model → Msg → Update → +View) - *Rust/Tauri 2.0* (backend, in src-tauri/) - *Deno* (runtime, +testing, build) - *Tailwind CSS 4.x* (styling) - No JSX — uses Tea_Html +functions (Tea_Html.div, Tea_Html.button, etc.) - No npm dependencies +except ReScript compiler itself - All state lives in `+model+` — no +global mutable state - SPDX header `+PMPL-1.0-or-later+` on ALL new +files - Panels are "`panels`" NEVER "`panes`" - Detailed annotations on +ALL code + +Work through each phase completely. Compile and test after each phase +before moving on. + +''''' + +=== PHASE 1 — Context-Sensitive Help & Hover-Overs (SMALLEST) + +Add tooltip and contextual help to every panel in PanLL. + +==== 1a. Create the help data model + +Create `+src/model/HelpModel.res+`: + +[source,rescript] +---- +// SPDX-License-Identifier: CC-BY-SA-4.0 +// HelpModel — tooltip and contextual help data for all panels + +type tooltipPosition = + | Above + | Below + | Left + | Right + +type helpEntry = { + id: string, // unique key, e.g. "panel-l.symbolic-mass" + title: string, // short title shown in tooltip header + summary: string, // one-line summary (shown on hover) + detail: string, // full explanation (shown on click/expand) + relatedPanels: array, // IDs of related panels + keywords: array, // for search +} + +type helpState = { + activeTooltip: option, // currently hovered help ID + expandedHelp: option, // currently expanded help entry + tooltipPosition: tooltipPosition, + searchQuery: string, + searchResults: array, + helpDatabase: Map.t, // all help entries +} +---- + +==== 1b. Create the help database + +Create `+src/core/HelpDatabase.res+` — populate with entries for every +panel. Read `+panel-clades/clades/+` to discover all panels and write a +`+helpEntry+` for each one. Include entries for: - All 3 core panels +(Panel-L, Panel-N, Panel-W) - All overlay panels (VAB, CloudGuard, Farm, +Fleet, Hypatia, etc.) - All cognitive governance concepts (Vexometer, +Anti-Crash Gate, Orbital Drift Aura, Information Humidity) - All +workspace modes (Rhodium, Everything, Code, Bespoke) - Key UI elements +(Panel Switcher, Capture Bar, Status Bar, Ribbon) - Key concepts +(eNSAID, TEA pattern, Binary Star Co-Orbit, Teranga, Umoja) + +==== 1c. Create the tooltip component + +Create `+src/components/Tooltip.res+`: - Renders a floating tooltip near +the cursor/element - Shows `+summary+` on hover - Expands to show +`+detail+` on click - Links to related panels - Dismisses on Escape or +clicking elsewhere - Styled with Tailwind (dark background, rounded +corners, subtle shadow) - Accessible: role="`tooltip`", aria-describedby + +==== 1d. Create the help overlay panel + +Create `+src/components/HelpOverlay.res+`: - Full-screen searchable help +browser - Search box at top — filters helpDatabase by keywords and +titles - Results shown as cards with title, summary, and click-to-expand +detail - Keyboard shortcut: `+Ctrl+Shift+H+` to open/close - Add to +panel switcher bar + +==== 1e. Wire help into existing panels + +For each existing panel component in `+src/components/+`: - Add +`+Tooltip.make+` calls on key UI elements - Pass the relevant +`+helpEntry.id+` so the correct tooltip appears - Don’t modify panel +logic — only add tooltip wrappers around existing elements + +==== 1f. Compile and test + +[source,bash] +---- +deno task res:build # Must compile with 0 errors +deno task test # All existing tests must still pass +---- + +''''' + +=== PHASE 2 — Wiki & Full Manuals (SMALL-MEDIUM) + +Create an integrated documentation wiki inside PanLL. + +==== 2a. Create wiki data model + +Create `+src/model/WikiModel.res+`: + +[source,rescript] +---- +// SPDX-License-Identifier: CC-BY-SA-4.0 +// WikiModel — integrated documentation wiki + +type wikiPage = { + slug: string, // URL-safe identifier + title: string, + content: string, // Markdown/A2ML content + category: wikiCategory, + lastUpdated: string, // ISO date + parentSlug: option, + childSlugs: array, + relatedHelpIds: array, // links to HelpDatabase entries +} + +and wikiCategory = + | GettingStarted + | CoreConcepts + | PanelReference + | Tutorials + | Architecture + | Troubleshooting + | Glossary +---- + +==== 2b. Create wiki content generator + +Create `+src/core/WikiContent.res+`: - Auto-generate a wiki page for +every panel from HelpDatabase entries + clade definitions - Include +these manual sections: 1. *Getting Started* — what is PanLL, first +launch, basic navigation 2. *Core Concepts* — eNSAID, Binary Star, TEA +pattern, panels vs panes (panels!), cognitive governance 3. *Panel +Reference* — one page per panel with purpose, keyboard shortcuts, +configuration options 4. *Tutorials* — step-by-step guides for common +tasks 5. *Architecture* — how PanLL is built, module map, data flow 6. +*Troubleshooting* — common issues and fixes 7. *Glossary* — all terms +defined + +==== 2c. Create wiki panel component + +Create `+src/components/Wiki.res+`: - Sidebar with category tree +navigation (collapsible sections) - Main content area rendering wiki +pages - Breadcrumb navigation at top - Search bar (reuses help search, +extended to wiki content) - "`Edit this page`" link (opens source in +editor via Editor Bridge panel) - Internal links between wiki pages +(click panel name → goes to panel reference page) - Keyboard shortcut: +`+Ctrl+Shift+W+` (W for wiki) — *ASK ME* if this conflicts with an +existing shortcut + +==== 2d. Context-sensitive wiki links + +Enhance each panel’s help tooltip (from Phase 1): - Add a "`Learn more +→`" link at the bottom of each expanded tooltip - Link goes directly to +that panel’s wiki page - Right-click any panel header → "`Open in Wiki`" +option + +==== 2e. Compile and test + +[source,bash] +---- +deno task res:build +deno task test +---- + +Write tests for wiki content generation (every panel must have a wiki +page). + +''''' + +=== PHASE 3 — Software Induction Walkthrough (MEDIUM) + +Build an interactive guided tour system — like those "`click here, then +here`" software onboarding experiences. + +==== 3a. Create tour data model + +Create `+src/model/TourModel.res+`: + +[source,rescript] +---- +// SPDX-License-Identifier: CC-BY-SA-4.0 +// TourModel — interactive guided tour / software induction + +type tourHighlight = + | PanelSwitcher + | StatusBar + | CaptureBar + | SpecificPanel(string) // panel ID + | UIElement(string) // CSS selector or element ID + | KeyboardShortcut(string) + +type tourStep = { + id: string, + title: string, + instruction: string, // "Click on the Panel Switcher..." + highlight: tourHighlight, // what to spotlight + expectedAction: option, // what the user should do + completionCheck: option, // condition to auto-advance + tipText: option, // bonus tip shown small +} + +and tourAction = + | ClickElement(string) + | PressKey(string) + | OpenPanel(string) + | ChangeMode(string) + | AnyAction // just do anything to continue + +type tour = { + id: string, + name: string, + description: string, + steps: array, + estimatedMinutes: int, +} + +type tourState = { + activeTour: option, + currentStep: int, + completedTours: array, + skipped: bool, +} +---- + +==== 3b. Create the tour definitions + +Create `+src/core/Tours.res+` with these built-in tours: + +*Tour 1: "`Welcome to PanLL`" (5 min)* 1. Welcome message — explain +eNSAID concept in 2 sentences 2. Highlight Panel-L → explain symbolic +panel 3. Highlight Panel-N → explain neural panel + ECHIDNA 4. Highlight +Panel-W → explain world/results panel 5. Highlight Panel Switcher → show +how to open overlay panels 6. Highlight Status Bar → explain what each +section shows 7. Try opening an overlay panel (VAB or Farm) 8. Try +cycling workspace modes (Ctrl+Shift+M) 9. Congratulations — you’re ready + +*Tour 2: "`Panels Deep Dive`" (10 min)* - Walk through each panel +category (governance, infra, game dev, etc.) - Open 3-4 representative +panels, explain what each does + +*Tour 3: "`Keyboard Power User`" (5 min)* - All keyboard shortcuts with +practice steps + +*Tour 4: "`Your First Custom Panel`" (15 min)* - Walk through the Minter +to create a panel from scratch - Provision it, configure isolation tier, +see it in the switcher + +*Tour 5: "`Game Development Setup`" (10 min)* - Walk through IDApTIK +panels specifically - Set up a game dev workspace mode + +==== 3c. Create the tour overlay component + +Create `+src/components/TourOverlay.res+`: - *Spotlight effect*: dims +everything except the highlighted element (CSS backdrop with cutout) - +*Speech bubble*: positioned next to the highlighted element with the +instruction text - *Progress bar*: shows step N of M - *Buttons*: +"`Next`", "`Back`", "`Skip Tour`" - *Auto-advance*: if +`+expectedAction+` is set, watch for it and advance automatically - +*Persist completion*: mark tours as completed so they don’t re-trigger - +First launch detection: if no tours completed, offer "`Welcome to +PanLL`" automatically + +==== 3d. Add tour launcher to UI + +* Add "`Guided Tours`" button to the help overlay (Phase 2) +* Add tour list to wiki Getting Started section +* On first ever launch, show a gentle prompt: "`Welcome! Would you like +a quick tour? (2 minutes)`" + +==== 3e. Compile and test + +[source,bash] +---- +deno task res:build +deno task test +---- + +Write tests for tour step sequencing and completion tracking. + +''''' + +=== PHASE 4 — Cognitive Ergonomics Modes (MEDIUM-LARGE) + +Add workspace focus modes that reshape PanLL based on what you’re doing. + +==== 4a. Extend workspace model + +In `+src/model/WorkspaceModel.res+`, add these new modes alongside the +existing ones (Rhodium, Everything, Code, Bespoke): + +[source,rescript] +---- +// New cognitive focus modes +type focusMode = + | GameLoop // game development focused + | DeepTheory // logic, maths, formal verification + | General // IDE support with neurosymbolic + agentic + | LearnStyle // adaptive — learns from usage patterns (Phase 6) +---- + +==== 4b. Define mode configurations + +Create `+src/core/FocusModes.res+`: + +*Game Loop Mode:* - Visible panels: Game Preview, Level Architect, VM +Inspector, Build Dashboard, Valence Shell, Coprocessors - Hidden: +Palimpsest Plaza, Reposystem, CloudGuard, Aerie (not game-relevant) - +Status bar shows: FPS, build status, test results, active players (if +multiplayer) - Colour theme: darker, less visual noise - Information +Humidity: Medium (balanced) - Panel-N advisor: game-dev focused prompts, +performance tips + +*Deep Theory Mode:* - Visible panels: Panel-L (prominent), Playgrounds, +Proof panel, Interfaces - Hidden: Fleet, CloudGuard, Farm, most infra +panels - Panel-L takes 60% of screen width (enlarged symbolic view) - +Panel-N advisor: proof tactics, type theory help, formal verification +guidance - Information Humidity: High (show everything — user wants +density) - Colour theme: high contrast, serif fonts for mathematical +notation - Status bar shows: proof obligations remaining, type-check +status + +*General Mode:* - Visible panels: all core panels balanced, Panel +Switcher prominent - Panel-N advisor: general coding help, neurosymbolic +suggestions - Information Humidity: Medium - Default keyboard shortcuts +active - This is the "`normal`" mode — IDE-like with NeSy + agentic +support + +==== 4c. Mode switching UI + +* Extend the workspace mode cycle (Ctrl+Shift+M) to include focus modes +* Add a mode picker dropdown in the Status Bar (click mode name → +dropdown with all modes) +* Each mode has an icon and one-line description +* Switching modes animates panels in/out (fade transition, 200ms) +* Mode persists across sessions (saved to Tauri filesystem) + +==== 4d. Mode-specific panel arrangements + +When entering a mode: 1. Save current arrangement as "`Previous`" (can +restore) 2. Apply mode’s panel visibility rules 3. Apply mode’s layout +rules (panel sizing, prominence) 4. Update Panel-N advisor context 5. +Update Information Humidity setting 6. Update Status Bar content + +==== 4e. Compile and test + +[source,bash] +---- +deno task res:build +deno task test +---- + +Write tests for mode switching, panel visibility rules, and state +persistence. + +''''' + +=== PHASE 5 — Agent Queues (LARGE) + +Build a system where users create named chains of little agents that run +in sequence with one click. + +==== 5a. Create agent queue model + +Create `+src/model/AgentQueueModel.res+`: + +[source,rescript] +---- +// SPDX-License-Identifier: CC-BY-SA-4.0 +// AgentQueueModel — user-defined agent chains + +type agentStep = { + id: string, + name: string, // e.g. "tidyTasks", "documentIt", "gatherTodos" + description: string, // what this agent does + prompt: string, // the instruction sent to the agent + cartridgeId: option, // BoJ cartridge to invoke (if any) + panelId: option, // PanLL panel to use (if any) + timeout: int, // max seconds before moving on + continueOnError: bool, // skip or abort on failure +} + +type agentQueue = { + id: string, + name: string, // user-chosen name, e.g. "Morning Standup" + description: string, + steps: array, + shortcutKey: option, // optional keyboard shortcut + ribbonIcon: option, // optional icon for quick access + lastRun: option, // ISO timestamp + runCount: int, +} + +type queueExecution = { + queueId: string, + currentStep: int, + stepResults: array, + status: executionStatus, + startedAt: string, +} + +and stepResult = { + stepId: string, + output: string, + success: bool, + durationMs: int, +} + +and executionStatus = + | Running + | Paused + | Completed + | Failed(string) + | Cancelled +---- + +==== 5b. Built-in agent queue templates + +Create `+src/core/AgentQueues.res+` with starter templates the user can +customise: + +[width="100%",cols="42%,25%,33%",options="header",] +|=== +|Queue Name |Steps |Purpose +|*tidyTasks* |scan TODOs → group by file → prioritise → update +STATE.a2ml |Clean up task tracking + +|*documentIt* |scan undocumented functions → generate docstrings → write +to files |Auto-document code + +|*gatherTodos* |grep TODOs/FIXMEs → format table → show in Panel-W +|Collect all TODOs + +|*preCommit* |run linter → run tests → run panic-attack → format summary +|Pre-commit checklist + +|*morningStandup* |check git log → check CI status → check open PRs → +summarise |Daily status + +|*reviewCode* |diff HEAD~1 → analyse changes → suggest improvements → +flag issues |Post-commit review + +|*securityScan* |run Hypatia → check dependencies → scan secrets → +report |Security audit +|=== + +==== 5c. Agent queue runner (Rust backend) + +Create `+src-tauri/src/agent_queue.rs+`: - Execute agent steps +sequentially - Stream output to Panel-W in real-time - Support +pause/resume/cancel - Invoke BoJ cartridges via HTTP when +`+cartridgeId+` is set - Log all runs to +`+~/.panll/agent-queue-history.json+` - Tauri commands: `+queue_run+`, +`+queue_pause+`, `+queue_cancel+`, `+queue_list+`, `+queue_save+`, +`+queue_delete+` + +==== 5d. Agent queue panel UI + +Create `+src/components/AgentQueue.res+`: - *Queue Library*: list all +saved queues as cards with name, description, step count, last run - +*Queue Builder*: drag-and-drop step ordering, add/remove steps, edit +each step’s prompt - *Queue Runner*: real-time execution view — current +step highlighted, output streaming, progress bar - *Quick Access +Ribbon*: horizontal strip at top of Panel-N with queue shortcut buttons +(user’s pinned queues) - One-click run: click queue card or ribbon +button → executes immediately - Keyboard shortcut assignment: +right-click queue → "`Assign shortcut`" → press key combo + +==== 5e. Wire into Panel-N + +The agent queue ribbon should appear at the top of Panel-N (the +neural/agentic panel): - Row of small icon buttons for pinned queues - +"`+`" button to create new queue - Click = run, right-click = +edit/configure - Running queue shows progress indicator on the ribbon +button + +==== 5f. Compile and test + +[source,bash] +---- +deno task res:build +deno task test +---- + +Write tests for queue execution order, pause/resume, error handling, and +step timeout. + +''''' + +=== PHASE 6 — "`Learn from my Style`" Mode (LARGEST) + +This is the adaptive mode that watches how the user works and suggests +panel arrangements and agent queues. + +==== 6a. Create usage tracking model + +Create `+src/model/StyleLearnerModel.res+`: + +[source,rescript] +---- +// SPDX-License-Identifier: CC-BY-SA-4.0 +// StyleLearnerModel — observes IDE usage patterns to suggest panels & workflows + +type usageEvent = { + timestamp: string, + eventType: usageEventType, + context: string, // what file/panel was active + metadata: Map.t, +} + +and usageEventType = + | PanelOpened(string) // which panel + | PanelClosed(string) + | PanelDwellTime(string, int) // panel ID, milliseconds spent + | KeyboardShortcutUsed(string) + | ModeChanged(string) // which mode + | AgentQueueRun(string) // which queue + | FileEdited(string) // file extension / language + | BoJCartridgeUsed(string) // which cartridge + | SearchPerformed(string) // help/wiki search query + | ErrorEncountered(string) // type of error + +type usagePattern = { + name: string, + description: string, + confidence: float, // 0.0 to 1.0 + detectedAt: string, + evidence: array, // human-readable reasons +} + +type styleSuggestion = { + id: string, + suggestionType: suggestionType, + title: string, + reason: string, // "You opened the Build Dashboard 12 times today..." + confidence: float, + dismissed: bool, + accepted: bool, +} + +and suggestionType = + | PinPanelToRibbon(string) // suggest adding panel to quick access + | CreateAgentQueue(agentStep) // suggest a new agent queue + | SuggestFocusMode(string) // suggest switching to a mode + | SuggestKeyboardShortcut(string, string) // action, suggested key + | SuggestPanelArrangement(array) // suggested visible panels + | RemoveUnusedPanel(string) // suggest hiding rarely-used panel +---- + +==== 6b. Create the pattern detector + +Create `+src/core/StyleDetector.res+`: + +Detect these patterns from usage history: + +[width="100%",cols="26%,41%,33%",options="header",] +|=== +|Pattern |Detection Rule |Suggestion +|*Frequent panel* |Panel opened > 5 times/session, 3+ sessions |Pin to +ribbon + +|*Unused panel* |Panel never opened in 5+ sessions |Offer to hide + +|*Repeated sequence* |Same 3+ panels opened in same order, 3+ times +|Create agent queue + +|*Time-of-day habit* |Consistent panel usage at similar times |Suggest +mode switch + +|*Language focus* |80%+ edits in one language for session |Suggest +language-specific panels + +|*Error cluster* |Same error type > 3 times in session |Suggest +troubleshooting panel + +|*Mode affinity* |User spends 80%+ time in one mode |Set as default mode + +|*Shortcut candidate* |Action performed > 10 times without shortcut +|Suggest keyboard shortcut +|=== + +Rules: - Only suggest with confidence > 0.6 - Never suggest more than 3 +things at once (avoid overwhelm) - Respect dismissals — don’t re-suggest +dismissed items for 7 days - All detection runs locally — no data leaves +the machine + +==== 6c. Create the suggestion UI + +Create `+src/components/StyleSuggestions.res+`: - Subtle notification +dot on Panel-N when suggestions are available - Click to see suggestion +cards - Each card has: title, reason (evidence-based), Accept / Dismiss +buttons - Accepted suggestions apply immediately (pin panel, create +queue, etc.) - "`Style Insights`" section: shows detected patterns as a +dashboard - "`You spend most time in Game Loop mode`" - "`Your most-used +panels: Build Dashboard, Game Preview, Valence Shell`" - "`Suggested +ribbon: [icons of top 5 panels]`" + +==== 6d. Usage data storage (Rust backend) + +Create `+src-tauri/src/style_learner.rs+`: - Store usage events in +`+~/.panll/usage-history.json+` (rolling 30-day window) - Auto-prune +events older than 30 days - Tauri commands: `+style_record_event+`, +`+style_get_patterns+`, `+style_get_suggestions+`, +`+style_dismiss_suggestion+`, `+style_accept_suggestion+` - Run pattern +detection on session start and every 30 minutes - Maximum file size: +10MB (auto-compact if exceeded) + +==== 6e. IDE observation bridge + +Enhance the Editor Bridge panel to emit `+usageEvent+` data: - File save +events → `+FileEdited+` with language/extension - Error diagnostics → +`+ErrorEncountered+` - Build results → relevant events - This connects +to the user’s actual code editor (VS Code, Neovim, etc.) via LSP +cartridge + +==== 6f. Wire "`Learn from my Style`" as a focus mode + +When the user selects "`Learn from my Style`" mode: - All panels visible +(like Everything mode) BUT ordered by usage frequency - Ribbon +auto-populated with most-used panels - Suggestions appear proactively +(notification dot pulses gently) - Panel-N advisor context: "`Based on +your patterns, here’s what might help…`" - After 2 weeks of learning, +offer to "`Crystallise`" — create a permanent Bespoke mode from learned +preferences + +==== 6g. Compile and test + +[source,bash] +---- +deno task res:build +deno task test +---- + +Write tests for: - Pattern detection accuracy (mock usage data → +expected patterns) - Suggestion generation (patterns → correct +suggestion types) - Dismissal/acceptance persistence - 30-day rolling +window cleanup - File size auto-compaction + +''''' + +=== FINAL VERIFICATION + +After all 6 phases: + +[arabic] +. `+deno task res:build+` — 0 errors, 0 warnings +. `+deno task test+` — all tests pass (original + new) +. Each new panel appears in the Panel Switcher +. Help tooltips work on all panels +. Wiki loads with pages for every panel +. Welcome tour runs on simulated first launch +. All 4 focus modes switch correctly +. Agent queue runner executes a template queue +. Style learner records events and generates patterns + +Show me a summary table: + +[cols=",,,",options="header",] +|=== +|Feature |Files Added |Tests Added |Status +|Context-Sensitive Help |? |? |✅/❌ +|Wiki & Manuals |? |? |✅/❌ +|Induction Walkthrough |? |? |✅/❌ +|Focus Modes |? |? |✅/❌ +|Agent Queues |? |? |✅/❌ +|Learn from my Style |? |? |✅/❌ +|=== + +*Done!* Tell me: "`All 6 features are built. PanLL now has contextual +help on every element, a searchable wiki, guided tours, 4 cognitive +focus modes, customisable agent queues, and adaptive style learning.`" diff --git a/docs/status/panll-features-build.md b/docs/status/panll-features-build.md deleted file mode 100644 index 4b578c5e..00000000 --- a/docs/status/panll-features-build.md +++ /dev/null @@ -1,656 +0,0 @@ -# PanLL Feature Build Script — Ordered Smallest → Largest -# SPDX-License-Identifier: CC-BY-SA-4.0 -# -# INSTRUCTIONS: Copy everything below the line into Claude Code as a single message. -# Claude will build each feature in order, asking questions where needed. -# Each phase completes and compiles before moving to the next. -# -# PREREQUISITES: PanLL must already be cloned and building. -# cd ~/Documents/hyperpolymath-repos/panll -# just build -# ───────────────────────────────────────────────────────────────────── - -I want you to build these PanLL features IN ORDER from smallest to largest. Before you start, read the AI manifest: - -``` -cat 0-AI-MANIFEST.a2ml -``` - -Then read the architecture: -``` -cat ARCHITECTURE.txt -cat TOPOLOGY.md -``` - -Then read the existing model, view, and update files to understand the TEA pattern: -``` -cat src/Model.res -cat src/View.res -cat src/Update.res (first 200 lines) -``` - -PanLL uses: -- **ReScript** (frontend, TEA pattern — Model → Msg → Update → View) -- **Rust/Tauri 2.0** (backend, in src-tauri/) -- **Deno** (runtime, testing, build) -- **Tailwind CSS 4.x** (styling) -- No JSX — uses Tea_Html functions (Tea_Html.div, Tea_Html.button, etc.) -- No npm dependencies except ReScript compiler itself -- All state lives in `model` — no global mutable state -- SPDX header `PMPL-1.0-or-later` on ALL new files -- Panels are "panels" NEVER "panes" -- Detailed annotations on ALL code - -Work through each phase completely. Compile and test after each phase before moving on. - ---- - -## PHASE 1 — Context-Sensitive Help & Hover-Overs (SMALLEST) - -Add tooltip and contextual help to every panel in PanLL. - -### 1a. Create the help data model - -Create `src/model/HelpModel.res`: -```rescript -// SPDX-License-Identifier: CC-BY-SA-4.0 -// HelpModel — tooltip and contextual help data for all panels - -type tooltipPosition = - | Above - | Below - | Left - | Right - -type helpEntry = { - id: string, // unique key, e.g. "panel-l.symbolic-mass" - title: string, // short title shown in tooltip header - summary: string, // one-line summary (shown on hover) - detail: string, // full explanation (shown on click/expand) - relatedPanels: array, // IDs of related panels - keywords: array, // for search -} - -type helpState = { - activeTooltip: option, // currently hovered help ID - expandedHelp: option, // currently expanded help entry - tooltipPosition: tooltipPosition, - searchQuery: string, - searchResults: array, - helpDatabase: Map.t, // all help entries -} -``` - -### 1b. Create the help database - -Create `src/core/HelpDatabase.res` — populate with entries for every panel. Read `panel-clades/clades/` to discover all panels and write a `helpEntry` for each one. Include entries for: -- All 3 core panels (Panel-L, Panel-N, Panel-W) -- All overlay panels (VAB, CloudGuard, Farm, Fleet, Hypatia, etc.) -- All cognitive governance concepts (Vexometer, Anti-Crash Gate, Orbital Drift Aura, Information Humidity) -- All workspace modes (Rhodium, Everything, Code, Bespoke) -- Key UI elements (Panel Switcher, Capture Bar, Status Bar, Ribbon) -- Key concepts (eNSAID, TEA pattern, Binary Star Co-Orbit, Teranga, Umoja) - -### 1c. Create the tooltip component - -Create `src/components/Tooltip.res`: -- Renders a floating tooltip near the cursor/element -- Shows `summary` on hover -- Expands to show `detail` on click -- Links to related panels -- Dismisses on Escape or clicking elsewhere -- Styled with Tailwind (dark background, rounded corners, subtle shadow) -- Accessible: role="tooltip", aria-describedby - -### 1d. Create the help overlay panel - -Create `src/components/HelpOverlay.res`: -- Full-screen searchable help browser -- Search box at top — filters helpDatabase by keywords and titles -- Results shown as cards with title, summary, and click-to-expand detail -- Keyboard shortcut: `Ctrl+Shift+H` to open/close -- Add to panel switcher bar - -### 1e. Wire help into existing panels - -For each existing panel component in `src/components/`: -- Add `Tooltip.make` calls on key UI elements -- Pass the relevant `helpEntry.id` so the correct tooltip appears -- Don't modify panel logic — only add tooltip wrappers around existing elements - -### 1f. Compile and test - -```bash -deno task res:build # Must compile with 0 errors -deno task test # All existing tests must still pass -``` - ---- - -## PHASE 2 — Wiki & Full Manuals (SMALL-MEDIUM) - -Create an integrated documentation wiki inside PanLL. - -### 2a. Create wiki data model - -Create `src/model/WikiModel.res`: -```rescript -// SPDX-License-Identifier: CC-BY-SA-4.0 -// WikiModel — integrated documentation wiki - -type wikiPage = { - slug: string, // URL-safe identifier - title: string, - content: string, // Markdown/A2ML content - category: wikiCategory, - lastUpdated: string, // ISO date - parentSlug: option, - childSlugs: array, - relatedHelpIds: array, // links to HelpDatabase entries -} - -and wikiCategory = - | GettingStarted - | CoreConcepts - | PanelReference - | Tutorials - | Architecture - | Troubleshooting - | Glossary -``` - -### 2b. Create wiki content generator - -Create `src/core/WikiContent.res`: -- Auto-generate a wiki page for every panel from HelpDatabase entries + clade definitions -- Include these manual sections: - 1. **Getting Started** — what is PanLL, first launch, basic navigation - 2. **Core Concepts** — eNSAID, Binary Star, TEA pattern, panels vs panes (panels!), cognitive governance - 3. **Panel Reference** — one page per panel with purpose, keyboard shortcuts, configuration options - 4. **Tutorials** — step-by-step guides for common tasks - 5. **Architecture** — how PanLL is built, module map, data flow - 6. **Troubleshooting** — common issues and fixes - 7. **Glossary** — all terms defined - -### 2c. Create wiki panel component - -Create `src/components/Wiki.res`: -- Sidebar with category tree navigation (collapsible sections) -- Main content area rendering wiki pages -- Breadcrumb navigation at top -- Search bar (reuses help search, extended to wiki content) -- "Edit this page" link (opens source in editor via Editor Bridge panel) -- Internal links between wiki pages (click panel name → goes to panel reference page) -- Keyboard shortcut: `Ctrl+Shift+W` (W for wiki) — **ASK ME** if this conflicts with an existing shortcut - -### 2d. Context-sensitive wiki links - -Enhance each panel's help tooltip (from Phase 1): -- Add a "Learn more →" link at the bottom of each expanded tooltip -- Link goes directly to that panel's wiki page -- Right-click any panel header → "Open in Wiki" option - -### 2e. Compile and test - -```bash -deno task res:build -deno task test -``` - -Write tests for wiki content generation (every panel must have a wiki page). - ---- - -## PHASE 3 — Software Induction Walkthrough (MEDIUM) - -Build an interactive guided tour system — like those "click here, then here" software onboarding experiences. - -### 3a. Create tour data model - -Create `src/model/TourModel.res`: -```rescript -// SPDX-License-Identifier: CC-BY-SA-4.0 -// TourModel — interactive guided tour / software induction - -type tourHighlight = - | PanelSwitcher - | StatusBar - | CaptureBar - | SpecificPanel(string) // panel ID - | UIElement(string) // CSS selector or element ID - | KeyboardShortcut(string) - -type tourStep = { - id: string, - title: string, - instruction: string, // "Click on the Panel Switcher..." - highlight: tourHighlight, // what to spotlight - expectedAction: option, // what the user should do - completionCheck: option, // condition to auto-advance - tipText: option, // bonus tip shown small -} - -and tourAction = - | ClickElement(string) - | PressKey(string) - | OpenPanel(string) - | ChangeMode(string) - | AnyAction // just do anything to continue - -type tour = { - id: string, - name: string, - description: string, - steps: array, - estimatedMinutes: int, -} - -type tourState = { - activeTour: option, - currentStep: int, - completedTours: array, - skipped: bool, -} -``` - -### 3b. Create the tour definitions - -Create `src/core/Tours.res` with these built-in tours: - -**Tour 1: "Welcome to PanLL" (5 min)** -1. Welcome message — explain eNSAID concept in 2 sentences -2. Highlight Panel-L → explain symbolic panel -3. Highlight Panel-N → explain neural panel + ECHIDNA -4. Highlight Panel-W → explain world/results panel -5. Highlight Panel Switcher → show how to open overlay panels -6. Highlight Status Bar → explain what each section shows -7. Try opening an overlay panel (VAB or Farm) -8. Try cycling workspace modes (Ctrl+Shift+M) -9. Congratulations — you're ready - -**Tour 2: "Panels Deep Dive" (10 min)** -- Walk through each panel category (governance, infra, game dev, etc.) -- Open 3-4 representative panels, explain what each does - -**Tour 3: "Keyboard Power User" (5 min)** -- All keyboard shortcuts with practice steps - -**Tour 4: "Your First Custom Panel" (15 min)** -- Walk through the Minter to create a panel from scratch -- Provision it, configure isolation tier, see it in the switcher - -**Tour 5: "Game Development Setup" (10 min)** -- Walk through IDApTIK panels specifically -- Set up a game dev workspace mode - -### 3c. Create the tour overlay component - -Create `src/components/TourOverlay.res`: -- **Spotlight effect**: dims everything except the highlighted element (CSS backdrop with cutout) -- **Speech bubble**: positioned next to the highlighted element with the instruction text -- **Progress bar**: shows step N of M -- **Buttons**: "Next", "Back", "Skip Tour" -- **Auto-advance**: if `expectedAction` is set, watch for it and advance automatically -- **Persist completion**: mark tours as completed so they don't re-trigger -- First launch detection: if no tours completed, offer "Welcome to PanLL" automatically - -### 3d. Add tour launcher to UI - -- Add "Guided Tours" button to the help overlay (Phase 2) -- Add tour list to wiki Getting Started section -- On first ever launch, show a gentle prompt: "Welcome! Would you like a quick tour? (2 minutes)" - -### 3e. Compile and test - -```bash -deno task res:build -deno task test -``` - -Write tests for tour step sequencing and completion tracking. - ---- - -## PHASE 4 — Cognitive Ergonomics Modes (MEDIUM-LARGE) - -Add workspace focus modes that reshape PanLL based on what you're doing. - -### 4a. Extend workspace model - -In `src/model/WorkspaceModel.res`, add these new modes alongside the existing ones (Rhodium, Everything, Code, Bespoke): - -```rescript -// New cognitive focus modes -type focusMode = - | GameLoop // game development focused - | DeepTheory // logic, maths, formal verification - | General // IDE support with neurosymbolic + agentic - | LearnStyle // adaptive — learns from usage patterns (Phase 6) -``` - -### 4b. Define mode configurations - -Create `src/core/FocusModes.res`: - -**Game Loop Mode:** -- Visible panels: Game Preview, Level Architect, VM Inspector, Build Dashboard, Valence Shell, Coprocessors -- Hidden: Palimpsest Plaza, Reposystem, CloudGuard, Aerie (not game-relevant) -- Status bar shows: FPS, build status, test results, active players (if multiplayer) -- Colour theme: darker, less visual noise -- Information Humidity: Medium (balanced) -- Panel-N advisor: game-dev focused prompts, performance tips - -**Deep Theory Mode:** -- Visible panels: Panel-L (prominent), Playgrounds, Proof panel, Interfaces -- Hidden: Fleet, CloudGuard, Farm, most infra panels -- Panel-L takes 60% of screen width (enlarged symbolic view) -- Panel-N advisor: proof tactics, type theory help, formal verification guidance -- Information Humidity: High (show everything — user wants density) -- Colour theme: high contrast, serif fonts for mathematical notation -- Status bar shows: proof obligations remaining, type-check status - -**General Mode:** -- Visible panels: all core panels balanced, Panel Switcher prominent -- Panel-N advisor: general coding help, neurosymbolic suggestions -- Information Humidity: Medium -- Default keyboard shortcuts active -- This is the "normal" mode — IDE-like with NeSy + agentic support - -### 4c. Mode switching UI - -- Extend the workspace mode cycle (Ctrl+Shift+M) to include focus modes -- Add a mode picker dropdown in the Status Bar (click mode name → dropdown with all modes) -- Each mode has an icon and one-line description -- Switching modes animates panels in/out (fade transition, 200ms) -- Mode persists across sessions (saved to Tauri filesystem) - -### 4d. Mode-specific panel arrangements - -When entering a mode: -1. Save current arrangement as "Previous" (can restore) -2. Apply mode's panel visibility rules -3. Apply mode's layout rules (panel sizing, prominence) -4. Update Panel-N advisor context -5. Update Information Humidity setting -6. Update Status Bar content - -### 4e. Compile and test - -```bash -deno task res:build -deno task test -``` - -Write tests for mode switching, panel visibility rules, and state persistence. - ---- - -## PHASE 5 — Agent Queues (LARGE) - -Build a system where users create named chains of little agents that run in sequence with one click. - -### 5a. Create agent queue model - -Create `src/model/AgentQueueModel.res`: -```rescript -// SPDX-License-Identifier: CC-BY-SA-4.0 -// AgentQueueModel — user-defined agent chains - -type agentStep = { - id: string, - name: string, // e.g. "tidyTasks", "documentIt", "gatherTodos" - description: string, // what this agent does - prompt: string, // the instruction sent to the agent - cartridgeId: option, // BoJ cartridge to invoke (if any) - panelId: option, // PanLL panel to use (if any) - timeout: int, // max seconds before moving on - continueOnError: bool, // skip or abort on failure -} - -type agentQueue = { - id: string, - name: string, // user-chosen name, e.g. "Morning Standup" - description: string, - steps: array, - shortcutKey: option, // optional keyboard shortcut - ribbonIcon: option, // optional icon for quick access - lastRun: option, // ISO timestamp - runCount: int, -} - -type queueExecution = { - queueId: string, - currentStep: int, - stepResults: array, - status: executionStatus, - startedAt: string, -} - -and stepResult = { - stepId: string, - output: string, - success: bool, - durationMs: int, -} - -and executionStatus = - | Running - | Paused - | Completed - | Failed(string) - | Cancelled -``` - -### 5b. Built-in agent queue templates - -Create `src/core/AgentQueues.res` with starter templates the user can customise: - -| Queue Name | Steps | Purpose | -|-----------|-------|---------| -| **tidyTasks** | scan TODOs → group by file → prioritise → update STATE.a2ml | Clean up task tracking | -| **documentIt** | scan undocumented functions → generate docstrings → write to files | Auto-document code | -| **gatherTodos** | grep TODOs/FIXMEs → format table → show in Panel-W | Collect all TODOs | -| **preCommit** | run linter → run tests → run panic-attack → format summary | Pre-commit checklist | -| **morningStandup** | check git log → check CI status → check open PRs → summarise | Daily status | -| **reviewCode** | diff HEAD~1 → analyse changes → suggest improvements → flag issues | Post-commit review | -| **securityScan** | run Hypatia → check dependencies → scan secrets → report | Security audit | - -### 5c. Agent queue runner (Rust backend) - -Create `src-tauri/src/agent_queue.rs`: -- Execute agent steps sequentially -- Stream output to Panel-W in real-time -- Support pause/resume/cancel -- Invoke BoJ cartridges via HTTP when `cartridgeId` is set -- Log all runs to `~/.panll/agent-queue-history.json` -- Tauri commands: `queue_run`, `queue_pause`, `queue_cancel`, `queue_list`, `queue_save`, `queue_delete` - -### 5d. Agent queue panel UI - -Create `src/components/AgentQueue.res`: -- **Queue Library**: list all saved queues as cards with name, description, step count, last run -- **Queue Builder**: drag-and-drop step ordering, add/remove steps, edit each step's prompt -- **Queue Runner**: real-time execution view — current step highlighted, output streaming, progress bar -- **Quick Access Ribbon**: horizontal strip at top of Panel-N with queue shortcut buttons (user's pinned queues) -- One-click run: click queue card or ribbon button → executes immediately -- Keyboard shortcut assignment: right-click queue → "Assign shortcut" → press key combo - -### 5e. Wire into Panel-N - -The agent queue ribbon should appear at the top of Panel-N (the neural/agentic panel): -- Row of small icon buttons for pinned queues -- "+" button to create new queue -- Click = run, right-click = edit/configure -- Running queue shows progress indicator on the ribbon button - -### 5f. Compile and test - -```bash -deno task res:build -deno task test -``` - -Write tests for queue execution order, pause/resume, error handling, and step timeout. - ---- - -## PHASE 6 — "Learn from my Style" Mode (LARGEST) - -This is the adaptive mode that watches how the user works and suggests panel arrangements and agent queues. - -### 6a. Create usage tracking model - -Create `src/model/StyleLearnerModel.res`: -```rescript -// SPDX-License-Identifier: CC-BY-SA-4.0 -// StyleLearnerModel — observes IDE usage patterns to suggest panels & workflows - -type usageEvent = { - timestamp: string, - eventType: usageEventType, - context: string, // what file/panel was active - metadata: Map.t, -} - -and usageEventType = - | PanelOpened(string) // which panel - | PanelClosed(string) - | PanelDwellTime(string, int) // panel ID, milliseconds spent - | KeyboardShortcutUsed(string) - | ModeChanged(string) // which mode - | AgentQueueRun(string) // which queue - | FileEdited(string) // file extension / language - | BoJCartridgeUsed(string) // which cartridge - | SearchPerformed(string) // help/wiki search query - | ErrorEncountered(string) // type of error - -type usagePattern = { - name: string, - description: string, - confidence: float, // 0.0 to 1.0 - detectedAt: string, - evidence: array, // human-readable reasons -} - -type styleSuggestion = { - id: string, - suggestionType: suggestionType, - title: string, - reason: string, // "You opened the Build Dashboard 12 times today..." - confidence: float, - dismissed: bool, - accepted: bool, -} - -and suggestionType = - | PinPanelToRibbon(string) // suggest adding panel to quick access - | CreateAgentQueue(agentStep) // suggest a new agent queue - | SuggestFocusMode(string) // suggest switching to a mode - | SuggestKeyboardShortcut(string, string) // action, suggested key - | SuggestPanelArrangement(array) // suggested visible panels - | RemoveUnusedPanel(string) // suggest hiding rarely-used panel -``` - -### 6b. Create the pattern detector - -Create `src/core/StyleDetector.res`: - -Detect these patterns from usage history: - -| Pattern | Detection Rule | Suggestion | -|---------|---------------|------------| -| **Frequent panel** | Panel opened > 5 times/session, 3+ sessions | Pin to ribbon | -| **Unused panel** | Panel never opened in 5+ sessions | Offer to hide | -| **Repeated sequence** | Same 3+ panels opened in same order, 3+ times | Create agent queue | -| **Time-of-day habit** | Consistent panel usage at similar times | Suggest mode switch | -| **Language focus** | 80%+ edits in one language for session | Suggest language-specific panels | -| **Error cluster** | Same error type > 3 times in session | Suggest troubleshooting panel | -| **Mode affinity** | User spends 80%+ time in one mode | Set as default mode | -| **Shortcut candidate** | Action performed > 10 times without shortcut | Suggest keyboard shortcut | - -Rules: -- Only suggest with confidence > 0.6 -- Never suggest more than 3 things at once (avoid overwhelm) -- Respect dismissals — don't re-suggest dismissed items for 7 days -- All detection runs locally — no data leaves the machine - -### 6c. Create the suggestion UI - -Create `src/components/StyleSuggestions.res`: -- Subtle notification dot on Panel-N when suggestions are available -- Click to see suggestion cards -- Each card has: title, reason (evidence-based), Accept / Dismiss buttons -- Accepted suggestions apply immediately (pin panel, create queue, etc.) -- "Style Insights" section: shows detected patterns as a dashboard - - "You spend most time in Game Loop mode" - - "Your most-used panels: Build Dashboard, Game Preview, Valence Shell" - - "Suggested ribbon: [icons of top 5 panels]" - -### 6d. Usage data storage (Rust backend) - -Create `src-tauri/src/style_learner.rs`: -- Store usage events in `~/.panll/usage-history.json` (rolling 30-day window) -- Auto-prune events older than 30 days -- Tauri commands: `style_record_event`, `style_get_patterns`, `style_get_suggestions`, `style_dismiss_suggestion`, `style_accept_suggestion` -- Run pattern detection on session start and every 30 minutes -- Maximum file size: 10MB (auto-compact if exceeded) - -### 6e. IDE observation bridge - -Enhance the Editor Bridge panel to emit `usageEvent` data: -- File save events → `FileEdited` with language/extension -- Error diagnostics → `ErrorEncountered` -- Build results → relevant events -- This connects to the user's actual code editor (VS Code, Neovim, etc.) via LSP cartridge - -### 6f. Wire "Learn from my Style" as a focus mode - -When the user selects "Learn from my Style" mode: -- All panels visible (like Everything mode) BUT ordered by usage frequency -- Ribbon auto-populated with most-used panels -- Suggestions appear proactively (notification dot pulses gently) -- Panel-N advisor context: "Based on your patterns, here's what might help..." -- After 2 weeks of learning, offer to "Crystallise" — create a permanent Bespoke mode from learned preferences - -### 6g. Compile and test - -```bash -deno task res:build -deno task test -``` - -Write tests for: -- Pattern detection accuracy (mock usage data → expected patterns) -- Suggestion generation (patterns → correct suggestion types) -- Dismissal/acceptance persistence -- 30-day rolling window cleanup -- File size auto-compaction - ---- - -## FINAL VERIFICATION - -After all 6 phases: - -1. `deno task res:build` — 0 errors, 0 warnings -2. `deno task test` — all tests pass (original + new) -3. Each new panel appears in the Panel Switcher -4. Help tooltips work on all panels -5. Wiki loads with pages for every panel -6. Welcome tour runs on simulated first launch -7. All 4 focus modes switch correctly -8. Agent queue runner executes a template queue -9. Style learner records events and generates patterns - -Show me a summary table: - -| Feature | Files Added | Tests Added | Status | -|---------|------------|-------------|--------| -| Context-Sensitive Help | ? | ? | ✅/❌ | -| Wiki & Manuals | ? | ? | ✅/❌ | -| Induction Walkthrough | ? | ? | ✅/❌ | -| Focus Modes | ? | ? | ✅/❌ | -| Agent Queues | ? | ? | ✅/❌ | -| Learn from my Style | ? | ? | ✅/❌ | - -**Done!** Tell me: "All 6 features are built. PanLL now has contextual help on every element, a searchable wiki, guided tours, 4 cognitive focus modes, customisable agent queues, and adaptive style learning." diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 00000000..134ebba2 --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,80 @@ +== Tech-Debt Audit — panll — 2026-05-26 + +*Source:* estate-wide automated scan 2026-05-26. *Companion:* +https://github.com/hyperpolymath/standards/tree/main/docs/audits[`+hyperpolymath/standards+` +2026-05-26-estate-*-debt audits]. *Combined severity:* `+LOW+`. + +This file records the _raw findings_ — it does not by itself fix the +debt. Each section ends with a '`Recommended next move`' line; closing +the debt is follow-up work. + +=== 1. Proof debt + +Scanner counted the following markers in proof-bearing files of this +repo: + +.... +files= 3 | Coq-Axm/Adm= 0 | Lean-srry/ax= 0 | Agda-pst= 0 | Idr-blv= 0 | Idr-prtl= 0 | Fstr-asm= 0 | TODO= 0 | Unsafe= 4 +.... + +*Total markers:* 4. *Severity:* `+>04+`. + +*Marker types* (any non-zero counts above): - Coq `+Axiom+`/`+Admitted+` +— unconditional proof escapes. - Lean `+sorry+`/`+axiom+` — Lean’s +equivalent. - Agda `+postulate+` — accepted axiomatically. - Idris2 +`+believe_me+`/`+assert_total+` — runtime-safe coercion / totality +assumption. - Idris2 top-level `+partial+` — totality-check waived. - F* +`+assume val+`/`+admit_p+` — F* admit. - `+TODO PROOF+` / `+OWED:+` — +self-documented debt markers. - `+unsafePerformIO+`/`+unsafeCoerce+` — +soundness-relevant escape hatches in Haskell/Rust source. + +*Recommended next move:* triage each finding into one of: (a) discharge +by proof, (b) cover with property-tests + a documented refutation +budget, or (c) annotate as a known/necessary axiom (e.g. `+funExt+`) in +`+docs/proof-debt.md+`. + +=== 2. Licence debt + +[cols=",",options="header",] +|=== +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+MPL-2.0+` +|Manifest licence |`+MPL-2.0+` +|Body classifier |`+MPL-2.0+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |318 +|`+docs/+` files |62 +|`+docs/+` LoC |19405 +|CHANGELOG.md |Y +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+OK+` +|=== + +*Recommended next move:* none for docs. + +=== Cross-references + +* Estate proof-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md+` +* Estate licence-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md+` +* Estate documentation-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md+` + +''''' + +🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). +This file is informational — closing the debt is follow-up work owned by +the maintainer. diff --git a/docs/tech-debt-2026-05-26.md b/docs/tech-debt-2026-05-26.md deleted file mode 100644 index 558f20ea..00000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,71 +0,0 @@ - - -# Tech-Debt Audit — panll — 2026-05-26 - -**Source:** estate-wide automated scan 2026-05-26. -**Companion:** [`hyperpolymath/standards` 2026-05-26-estate-*-debt audits](https://github.com/hyperpolymath/standards/tree/main/docs/audits). -**Combined severity:** `LOW`. - -This file records the *raw findings* — it does not by itself fix the debt. Each section ends with a 'Recommended next move' line; closing the debt is follow-up work. - -## 1. Proof debt - -Scanner counted the following markers in proof-bearing files of this repo: - -``` -files= 3 | Coq-Axm/Adm= 0 | Lean-srry/ax= 0 | Agda-pst= 0 | Idr-blv= 0 | Idr-prtl= 0 | Fstr-asm= 0 | TODO= 0 | Unsafe= 4 -``` - -**Total markers:** 4. **Severity:** `>04`. - -**Marker types** (any non-zero counts above): -- Coq `Axiom`/`Admitted` — unconditional proof escapes. -- Lean `sorry`/`axiom` — Lean's equivalent. -- Agda `postulate` — accepted axiomatically. -- Idris2 `believe_me`/`assert_total` — runtime-safe coercion / totality assumption. -- Idris2 top-level `partial` — totality-check waived. -- F\* `assume val`/`admit_p` — F\* admit. -- `TODO PROOF` / `OWED:` — self-documented debt markers. -- `unsafePerformIO`/`unsafeCoerce` — soundness-relevant escape hatches in Haskell/Rust source. - -**Recommended next move:** triage each finding into one of: (a) discharge by proof, (b) cover with property-tests + a documented refutation budget, or (c) annotate as a known/necessary axiom (e.g. `funExt`) in `docs/proof-debt.md`. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `MPL-2.0` | -| Manifest licence | `MPL-2.0` | -| Body classifier | `MPL-2.0` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 318 | -| `docs/` files | 62 | -| `docs/` LoC | 19405 | -| CHANGELOG.md | Y | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `OK` | - -**Recommended next move:** none for docs. - -## Cross-references - -- Estate proof-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md` -- Estate licence-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md` -- Estate documentation-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md` - ---- - -🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). This file is informational — closing the debt is follow-up work owned by the maintainer. diff --git a/docs/troubleshooting.adoc b/docs/troubleshooting.adoc new file mode 100644 index 00000000..e2499aae --- /dev/null +++ b/docs/troubleshooting.adoc @@ -0,0 +1,564 @@ +== PanLL Identity Management Troubleshooting Guide + +=== Common Issues and Solutions + +==== VeriSimDB Connection Issues + +===== Symptom: "`VeriSimDB unavailable`" errors + +*Possible Causes*: - VeriSimDB service not running - Incorrect URL +configuration - Network connectivity problems - Authentication issues + +*Solutions*: + +[arabic] +. *Check VeriSimDB service status*: ++ +[source,bash] +---- +# Check if service is running +systemctl status verisimdb + +# Or check container status +docker ps | grep verisimdb +---- +. *Verify configuration*: ++ +[source,bash] +---- +# Check environment variable +echo $VERISIMDB_URL + +# Should return: http://localhost:8080/api/v1 (or your custom URL) +---- +. *Test connectivity*: ++ +[source,bash] +---- +curl -v http://localhost:8080/api/v1/health +---- +. *Check PanLL logs*: ++ +[source,bash] +---- +# Look for connection errors +journalctl -u panll --no-pager | grep -i verisim +---- + +===== Symptom: Fallback to filesystem storage + +*Expected Behavior*: This is normal when VeriSimDB is unavailable. PanLL +will: - Continue working normally - Store snapshots locally in +`+~/.panll/identities/+` - Automatically sync when VeriSimDB connection +is restored + +*Verification*: + +[source,bash] +---- +# Check local snapshots +ls -la ~/.panll/identities/ +---- + +==== Identity Snapshot Issues + +===== Symptom: "`Snapshot not found`" errors + +*Possible Causes*: - Invalid snapshot ID - Snapshot stored only in +VeriSimDB (not synced locally) - Snapshot corrupted - Permissions issue + +*Solutions*: + +[arabic] +. *List available snapshots*: ++ +[source,javascript] +---- +const snapshots = await invoke("identity_list"); +console.log("Available snapshots:", snapshots); +---- +. *Check both storage locations*: ++ +[source,bash] +---- +# Check VeriSimDB (if available) +curl http://localhost:8080/api/v1/state/ + +# Check local storage +ls ~/.panll/identities/ +---- +. *Verify snapshot ID format*: +* Should be UUID format: `+xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx+` +* No spaces or special characters + +===== Symptom: Corrupted snapshot files + +*Possible Causes*: - Incomplete write operation - Filesystem errors - +Manual file editing + +*Solutions*: + +[arabic] +. *Validate snapshot JSON*: ++ +[source,bash] +---- +# Check JSON validity +jq . ~/.panll/identities/snapshot-id.json +---- +. *Restore from VeriSimDB* (if available): ++ +[source,javascript] +---- +// Force load from VeriSimDB +const snapshot = await invoke("verisim_load_state", { + key: "your-snapshot-id" +}); + +// Re-save to fix local copy +await invoke("identity_save", { + name: snapshot.name, + panll_state: snapshot.panll_state, + settings: snapshot.settings, + service_urls: snapshot.service_urls +}); +---- +. *Manual repair* (advanced): +* Make backup of corrupted file +* Edit JSON to fix syntax errors +* Validate with `+jq+` before using + +==== Team Broadcast Issues + +===== Symptom: Team broadcasts not received + +*Possible Causes*: - Burble service not running - Network connectivity +issues - Incorrect Burble URL configuration - Firewall blocking +broadcasts + +*Solutions*: + +[arabic] +. *Check Burble service status*: ++ +[source,bash] +---- +systemctl status burble +# or +docker ps | grep burble +---- +. *Verify Burble configuration*: ++ +[source,bash] +---- +echo $BURBLE_URL +# Should return: http://localhost:6473 (or your custom URL) +---- +. *Test Burble connectivity*: ++ +[source,bash] +---- +curl -v http://localhost:6473/api/v1/status +---- +. *Check system tray notifications*: +* Right-click PanLL system tray icon +* Check "`Burble Status`" menu item +* Should show "`Connected`" when working + +===== Symptom: Broadcast received but won’t apply + +*Possible Causes*: - Incompatible snapshot version - Missing required +services - Permission restrictions - Conflicting local changes + +*Solutions*: + +[arabic] +. *Check snapshot compatibility*: ++ +[source,javascript] +---- +// Inspect snapshot before applying +const snapshot = await invoke("identity_load", { id: broadcastId }); +console.log("Snapshot details:", snapshot); +---- +. *Manual application*: ++ +[source,javascript] +---- +// Apply parts of snapshot selectively +const snapshot = await invoke("identity_load", { id: broadcastId }); + +// Apply only settings (example) +const settings = JSON.parse(snapshot.settings); +await invoke("settings_set", { + key: "some_setting", + value: settings.some_setting +}); +---- +. *Check service availability*: ++ +[source,javascript] +---- +// Verify required services are running +const services = await invoke("service_status_all"); +console.log("Service status:", services); +---- + +==== System Tray Issues + +===== Symptom: System tray icon missing + +*Possible Causes*: - PanLL not running - System tray service crashed - +Display/WM issues + +*Solutions*: + +[arabic] +. *Restart PanLL*: ++ +[source,bash] +---- +systemctl restart panll +# or +pkill panll; panll & +---- +. *Check system tray service*: ++ +[source,bash] +---- +# Reinitialize system tray +await invoke("system_tray_init"); +---- +. *Verify display environment*: ++ +[source,bash] +---- +echo $XDG_CURRENT_DESKTOP +echo $DESKTOP_SESSION +---- + +===== Symptom: Service toggle not working + +*Possible Causes*: - Service not installed - Permission issues - Service +crashed - Configuration error + +*Solutions*: + +[arabic] +. *Check service status*: ++ +[source,javascript] +---- +// Get current status +const burbleStatus = await invoke("system_tray_get_burble_status"); +const gossamerStatus = await invoke("system_tray_get_gossamer_status"); +---- +. *Manual service control*: ++ +[source,bash] +---- +# For Burble +systemctl restart burble + +# For Gossamer +systemctl restart gossamer +---- +. *Check logs*: ++ +[source,bash] +---- +journalctl -u burble -u gossamer --no-pager | tail -50 +---- + +==== Performance Issues + +===== Symptom: Slow snapshot operations + +*Possible Causes*: - VeriSimDB under heavy load - Large snapshot sizes - +Network latency - Filesystem performance issues + +*Solutions*: + +[arabic] +. *Check VeriSimDB performance*: ++ +[source,bash] +---- +curl http://localhost:8080/api/v1/stats +---- +. *Optimize snapshot size*: +* Remove unnecessary data before saving +* Compress large configuration objects +. *Monitor operation times*: ++ +[source,javascript] +---- +const start = performance.now(); +await invoke("identity_save", { /* ... */ }); +const duration = performance.now() - start; +console.log(`Save took ${duration}ms`); +---- +. *Fallback to local storage* (temporary): ++ +[source,bash] +---- +# Temporarily disable VeriSimDB +export VERISIMDB_URL="" +# Operations will use local storage only +---- + +==== Configuration Issues + +===== Symptom: Settings not persisting + +*Possible Causes*: - Permission issues - Corrupted settings file - Race +conditions + +*Solutions*: + +[arabic] +. *Check settings file*: ++ +[source,bash] +---- +ls -la ~/.panll/settings.json +jq . ~/.panll/settings.json +---- +. *Reset settings*: ++ +[source,javascript] +---- +await invoke("settings_reset"); +---- +. *Manual backup/restore*: ++ +[source,bash] +---- +# Backup +cp ~/.panll/settings.json ~/.panll/settings.json.bak + +# Restore +cp ~/.panll/settings.json.bak ~/.panll/settings.json +---- + +=== Advanced Troubleshooting + +==== Debug Logging + +Enable debug logging for detailed troubleshooting: + +[source,bash] +---- +# Set debug environment variable +export PANLL_DEBUG=1 + +# Run PanLL +panll + +# Check debug logs +tail -f ~/.panll/debug.log +---- + +==== Network Diagnostics + +[source,bash] +---- +# Check VeriSimDB connectivity +curl -v http://localhost:8080/api/v1/health + +# Check Burble connectivity +curl -v http://localhost:6473/api/v1/status + +# Test with different timeouts +curl --connect-timeout 5 --max-time 10 http://localhost:8080/api/v1/health +---- + +==== Manual VeriSimDB Operations + +[source,bash] +---- +# Save snapshot manually to VeriSimDB +SNAPSHOT_ID="your-snapshot-id" +SNAPSHOT_DATA='{"name":"Test","created_at":"2024-01-01T00:00:00Z"}' + +curl -X POST \ + http://localhost:8080/api/v1/state/$SNAPSHOT_ID \ + -H "Content-Type: application/json" \ + -d "{\"state\": $SNAPSHOT_DATA}" + +# Load snapshot manually from VeriSimDB +curl http://localhost:8080/api/v1/state/$SNAPSHOT_ID +---- + +==== Filesystem Verification + +[source,bash] +---- +# Check filesystem integrity +fsck ~/.panll/identities/ + +# Verify file permissions +chmod -R 600 ~/.panll/identities/ +chown -R $USER:$USER ~/.panll/ +---- + +=== Common Error Messages + +==== "`JSON serialise error`" + +*Cause*: Invalid JSON data in snapshot + +*Solution*: Validate all input data before saving + +[source,javascript] +---- +// Validate before saving +try { + JSON.parse(panll_state); + JSON.parse(settings); + JSON.parse(service_urls); + await invoke("identity_save", { /* ... */ }); +} catch (e) { + console.error("Invalid JSON:", e.message); +} +---- + +==== "`HTTP client error`" + +*Cause*: Network or VeriSimDB connection issue + +*Solution*: Check network connectivity and VeriSimDB status + +==== "`Snapshot not found`" + +*Cause*: Snapshot doesn’t exist in either storage location + +*Solution*: Verify snapshot ID and check both VeriSimDB and local +storage + +==== "`Broadcast failed`" + +*Cause*: Burble service issue or network problem + +*Solution*: Check Burble service status and network connectivity + +=== Recovery Procedures + +==== Restore from Backup + +[source,bash] +---- +# Restore entire identities directory +cp -r ~/.panll/backups/identities/ ~/.panll/ + +# Restore specific snapshot +cp ~/.panll/backups/identities/snapshot-id.json ~/.panll/identities/ +---- + +==== Manual Snapshot Migration + +[source,javascript] +---- +// Migrate from old format to new format +const oldSnapshot = { /* old format data */ }; + +const newSnapshot = { + id: oldSnapshot.id || uuid.v4(), + name: oldSnapshot.name || "Migrated Snapshot", + created_at: oldSnapshot.created_at || new Date().toISOString(), + panll_state: JSON.stringify(oldSnapshot.state || {}), + settings: JSON.stringify(oldSnapshot.settings || {}), + service_urls: JSON.stringify(oldSnapshot.services || {}) +}; + +await invoke("identity_save", newSnapshot); +---- + +==== Emergency Mode + +If all else fails, you can run PanLL in emergency mode: + +[source,bash] +---- +# Disable all external services +export VERISIMDB_URL="" +export BURBLE_URL="" +export DISABLE_SYSTEM_TRAY=1 + +# Run with minimal functionality +panll --safe-mode +---- + +=== Getting Help + +==== Diagnostic Information to Provide + +When reporting issues, include: + +[arabic] +. PanLL version (`+panll --version+`) +. Operating system and version +. VeriSimDB version (if applicable) +. Steps to reproduce the issue +. Relevant log entries +. Screenshot (if UI-related) + +==== Support Channels + +* *GitHub Issues*: https://github.com/hyperpolymath/panll/issues +* *Discussions*: https://github.com/hyperpolymath/panll/discussions +* *Documentation*: https://panll.hyperpolymath.dev/docs + +=== Preventive Measures + +==== Regular Maintenance + +[source,bash] +---- +# Weekly maintenance script +#!/bin/bash + +# Backup identities +tar -czf ~/.panll/backups/identities-$(date +%Y%m%d).tar.gz ~/.panll/identities/ + +# Clean up old backups +find ~/.panll/backups/ -name "*.tar.gz" -mtime +30 -delete + +# Verify snapshot integrity +find ~/.panll/identities/ -name "*.json" -exec jq . {} \; 2>/dev/null +---- + +==== Monitoring + +Set up monitoring for critical services: + +[source,bash] +---- +# Simple health check script +#!/bin/bash + +# Check VeriSimDB +if ! curl -s http://localhost:8080/api/v1/health >/dev/null; then + echo "VeriSimDB down!" | systemd-cat -p emerg +fi + +# Check Burble +if ! curl -s http://localhost:6473/api/v1/status >/dev/null; then + echo "Burble down!" | systemd-cat -p emerg +fi +---- + +==== Configuration Best Practices + +[arabic] +. *Use environment variables* for service URLs +. *Regular backups* of identity snapshots +. *Monitor service health* proactively +. *Test fallback mechanisms* periodically +. *Document team workflows* for consistency + +=== Related Documentation + +* link:identity-user-guide.md[User Guide] +* link:api-reference.md[API Reference] +* link:../README.adoc[PanLL README] diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md deleted file mode 100644 index 73f32105..00000000 --- a/docs/troubleshooting.md +++ /dev/null @@ -1,532 +0,0 @@ -# PanLL Identity Management Troubleshooting Guide - -## Common Issues and Solutions - -### VeriSimDB Connection Issues - -#### Symptom: "VeriSimDB unavailable" errors - -**Possible Causes**: -- VeriSimDB service not running -- Incorrect URL configuration -- Network connectivity problems -- Authentication issues - -**Solutions**: - -1. **Check VeriSimDB service status**: - ```bash - # Check if service is running - systemctl status verisimdb - - # Or check container status - docker ps | grep verisimdb - ``` - -2. **Verify configuration**: - ```bash - # Check environment variable - echo $VERISIMDB_URL - - # Should return: http://localhost:8080/api/v1 (or your custom URL) - ``` - -3. **Test connectivity**: - ```bash - curl -v http://localhost:8080/api/v1/health - ``` - -4. **Check PanLL logs**: - ```bash - # Look for connection errors - journalctl -u panll --no-pager | grep -i verisim - ``` - -#### Symptom: Fallback to filesystem storage - -**Expected Behavior**: This is normal when VeriSimDB is unavailable. PanLL will: -- Continue working normally -- Store snapshots locally in `~/.panll/identities/` -- Automatically sync when VeriSimDB connection is restored - -**Verification**: -```bash -# Check local snapshots -ls -la ~/.panll/identities/ -``` - -### Identity Snapshot Issues - -#### Symptom: "Snapshot not found" errors - -**Possible Causes**: -- Invalid snapshot ID -- Snapshot stored only in VeriSimDB (not synced locally) -- Snapshot corrupted -- Permissions issue - -**Solutions**: - -1. **List available snapshots**: - ```javascript - const snapshots = await invoke("identity_list"); - console.log("Available snapshots:", snapshots); - ``` - -2. **Check both storage locations**: - ```bash - # Check VeriSimDB (if available) - curl http://localhost:8080/api/v1/state/ - - # Check local storage - ls ~/.panll/identities/ - ``` - -3. **Verify snapshot ID format**: - - Should be UUID format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` - - No spaces or special characters - -#### Symptom: Corrupted snapshot files - -**Possible Causes**: -- Incomplete write operation -- Filesystem errors -- Manual file editing - -**Solutions**: - -1. **Validate snapshot JSON**: - ```bash - # Check JSON validity - jq . ~/.panll/identities/snapshot-id.json - ``` - -2. **Restore from VeriSimDB** (if available): - ```javascript - // Force load from VeriSimDB - const snapshot = await invoke("verisim_load_state", { - key: "your-snapshot-id" - }); - - // Re-save to fix local copy - await invoke("identity_save", { - name: snapshot.name, - panll_state: snapshot.panll_state, - settings: snapshot.settings, - service_urls: snapshot.service_urls - }); - ``` - -3. **Manual repair** (advanced): - - Make backup of corrupted file - - Edit JSON to fix syntax errors - - Validate with `jq` before using - -### Team Broadcast Issues - -#### Symptom: Team broadcasts not received - -**Possible Causes**: -- Burble service not running -- Network connectivity issues -- Incorrect Burble URL configuration -- Firewall blocking broadcasts - -**Solutions**: - -1. **Check Burble service status**: - ```bash - systemctl status burble - # or - docker ps | grep burble - ``` - -2. **Verify Burble configuration**: - ```bash - echo $BURBLE_URL - # Should return: http://localhost:6473 (or your custom URL) - ``` - -3. **Test Burble connectivity**: - ```bash - curl -v http://localhost:6473/api/v1/status - ``` - -4. **Check system tray notifications**: - - Right-click PanLL system tray icon - - Check "Burble Status" menu item - - Should show "Connected" when working - -#### Symptom: Broadcast received but won't apply - -**Possible Causes**: -- Incompatible snapshot version -- Missing required services -- Permission restrictions -- Conflicting local changes - -**Solutions**: - -1. **Check snapshot compatibility**: - ```javascript - // Inspect snapshot before applying - const snapshot = await invoke("identity_load", { id: broadcastId }); - console.log("Snapshot details:", snapshot); - ``` - -2. **Manual application**: - ```javascript - // Apply parts of snapshot selectively - const snapshot = await invoke("identity_load", { id: broadcastId }); - - // Apply only settings (example) - const settings = JSON.parse(snapshot.settings); - await invoke("settings_set", { - key: "some_setting", - value: settings.some_setting - }); - ``` - -3. **Check service availability**: - ```javascript - // Verify required services are running - const services = await invoke("service_status_all"); - console.log("Service status:", services); - ``` - -### System Tray Issues - -#### Symptom: System tray icon missing - -**Possible Causes**: -- PanLL not running -- System tray service crashed -- Display/WM issues - -**Solutions**: - -1. **Restart PanLL**: - ```bash - systemctl restart panll - # or - pkill panll; panll & - ``` - -2. **Check system tray service**: - ```bash - # Reinitialize system tray - await invoke("system_tray_init"); - ``` - -3. **Verify display environment**: - ```bash - echo $XDG_CURRENT_DESKTOP - echo $DESKTOP_SESSION - ``` - -#### Symptom: Service toggle not working - -**Possible Causes**: -- Service not installed -- Permission issues -- Service crashed -- Configuration error - -**Solutions**: - -1. **Check service status**: - ```javascript - // Get current status - const burbleStatus = await invoke("system_tray_get_burble_status"); - const gossamerStatus = await invoke("system_tray_get_gossamer_status"); - ``` - -2. **Manual service control**: - ```bash - # For Burble - systemctl restart burble - - # For Gossamer - systemctl restart gossamer - ``` - -3. **Check logs**: - ```bash - journalctl -u burble -u gossamer --no-pager | tail -50 - ``` - -### Performance Issues - -#### Symptom: Slow snapshot operations - -**Possible Causes**: -- VeriSimDB under heavy load -- Large snapshot sizes -- Network latency -- Filesystem performance issues - -**Solutions**: - -1. **Check VeriSimDB performance**: - ```bash - curl http://localhost:8080/api/v1/stats - ``` - -2. **Optimize snapshot size**: - - Remove unnecessary data before saving - - Compress large configuration objects - -3. **Monitor operation times**: - ```javascript - const start = performance.now(); - await invoke("identity_save", { /* ... */ }); - const duration = performance.now() - start; - console.log(`Save took ${duration}ms`); - ``` - -4. **Fallback to local storage** (temporary): - ```bash - # Temporarily disable VeriSimDB - export VERISIMDB_URL="" - # Operations will use local storage only - ``` - -### Configuration Issues - -#### Symptom: Settings not persisting - -**Possible Causes**: -- Permission issues -- Corrupted settings file -- Race conditions - -**Solutions**: - -1. **Check settings file**: - ```bash - ls -la ~/.panll/settings.json - jq . ~/.panll/settings.json - ``` - -2. **Reset settings**: - ```javascript - await invoke("settings_reset"); - ``` - -3. **Manual backup/restore**: - ```bash - # Backup - cp ~/.panll/settings.json ~/.panll/settings.json.bak - - # Restore - cp ~/.panll/settings.json.bak ~/.panll/settings.json - ``` - -## Advanced Troubleshooting - -### Debug Logging - -Enable debug logging for detailed troubleshooting: - -```bash -# Set debug environment variable -export PANLL_DEBUG=1 - -# Run PanLL -panll - -# Check debug logs -tail -f ~/.panll/debug.log -``` - -### Network Diagnostics - -```bash -# Check VeriSimDB connectivity -curl -v http://localhost:8080/api/v1/health - -# Check Burble connectivity -curl -v http://localhost:6473/api/v1/status - -# Test with different timeouts -curl --connect-timeout 5 --max-time 10 http://localhost:8080/api/v1/health -``` - -### Manual VeriSimDB Operations - -```bash -# Save snapshot manually to VeriSimDB -SNAPSHOT_ID="your-snapshot-id" -SNAPSHOT_DATA='{"name":"Test","created_at":"2024-01-01T00:00:00Z"}' - -curl -X POST \ - http://localhost:8080/api/v1/state/$SNAPSHOT_ID \ - -H "Content-Type: application/json" \ - -d "{\"state\": $SNAPSHOT_DATA}" - -# Load snapshot manually from VeriSimDB -curl http://localhost:8080/api/v1/state/$SNAPSHOT_ID -``` - -### Filesystem Verification - -```bash -# Check filesystem integrity -fsck ~/.panll/identities/ - -# Verify file permissions -chmod -R 600 ~/.panll/identities/ -chown -R $USER:$USER ~/.panll/ -``` - -## Common Error Messages - -### "JSON serialise error" - -**Cause**: Invalid JSON data in snapshot - -**Solution**: Validate all input data before saving - -```javascript -// Validate before saving -try { - JSON.parse(panll_state); - JSON.parse(settings); - JSON.parse(service_urls); - await invoke("identity_save", { /* ... */ }); -} catch (e) { - console.error("Invalid JSON:", e.message); -} -``` - -### "HTTP client error" - -**Cause**: Network or VeriSimDB connection issue - -**Solution**: Check network connectivity and VeriSimDB status - -### "Snapshot not found" - -**Cause**: Snapshot doesn't exist in either storage location - -**Solution**: Verify snapshot ID and check both VeriSimDB and local storage - -### "Broadcast failed" - -**Cause**: Burble service issue or network problem - -**Solution**: Check Burble service status and network connectivity - -## Recovery Procedures - -### Restore from Backup - -```bash -# Restore entire identities directory -cp -r ~/.panll/backups/identities/ ~/.panll/ - -# Restore specific snapshot -cp ~/.panll/backups/identities/snapshot-id.json ~/.panll/identities/ -``` - -### Manual Snapshot Migration - -```javascript -// Migrate from old format to new format -const oldSnapshot = { /* old format data */ }; - -const newSnapshot = { - id: oldSnapshot.id || uuid.v4(), - name: oldSnapshot.name || "Migrated Snapshot", - created_at: oldSnapshot.created_at || new Date().toISOString(), - panll_state: JSON.stringify(oldSnapshot.state || {}), - settings: JSON.stringify(oldSnapshot.settings || {}), - service_urls: JSON.stringify(oldSnapshot.services || {}) -}; - -await invoke("identity_save", newSnapshot); -``` - -### Emergency Mode - -If all else fails, you can run PanLL in emergency mode: - -```bash -# Disable all external services -export VERISIMDB_URL="" -export BURBLE_URL="" -export DISABLE_SYSTEM_TRAY=1 - -# Run with minimal functionality -panll --safe-mode -``` - -## Getting Help - -### Diagnostic Information to Provide - -When reporting issues, include: - -1. PanLL version (`panll --version`) -2. Operating system and version -3. VeriSimDB version (if applicable) -4. Steps to reproduce the issue -5. Relevant log entries -6. Screenshot (if UI-related) - -### Support Channels - -- **GitHub Issues**: https://github.com/hyperpolymath/panll/issues -- **Discussions**: https://github.com/hyperpolymath/panll/discussions -- **Documentation**: https://panll.hyperpolymath.dev/docs - -## Preventive Measures - -### Regular Maintenance - -```bash -# Weekly maintenance script -#!/bin/bash - -# Backup identities -tar -czf ~/.panll/backups/identities-$(date +%Y%m%d).tar.gz ~/.panll/identities/ - -# Clean up old backups -find ~/.panll/backups/ -name "*.tar.gz" -mtime +30 -delete - -# Verify snapshot integrity -find ~/.panll/identities/ -name "*.json" -exec jq . {} \; 2>/dev/null -``` - -### Monitoring - -Set up monitoring for critical services: - -```bash -# Simple health check script -#!/bin/bash - -# Check VeriSimDB -if ! curl -s http://localhost:8080/api/v1/health >/dev/null; then - echo "VeriSimDB down!" | systemd-cat -p emerg -fi - -# Check Burble -if ! curl -s http://localhost:6473/api/v1/status >/dev/null; then - echo "Burble down!" | systemd-cat -p emerg -fi -``` - -### Configuration Best Practices - -1. **Use environment variables** for service URLs -2. **Regular backups** of identity snapshots -3. **Monitor service health** proactively -4. **Test fallback mechanisms** periodically -5. **Document team workflows** for consistency - -## Related Documentation - -- [User Guide](identity-user-guide.md) -- [API Reference](api-reference.md) -- [PanLL README](../README.adoc) \ No newline at end of file diff --git a/docs/v0.2.1-enhancements.adoc b/docs/v0.2.1-enhancements.adoc new file mode 100644 index 00000000..f0481812 --- /dev/null +++ b/docs/v0.2.1-enhancements.adoc @@ -0,0 +1,426 @@ +== PanLL v0.2.1 Enhancement Plan + +=== Overview + +PanLL v0.2.1 focuses on *UI improvements* and *performance +optimizations* to enhance the user experience of the Connected +Workbench. This release builds on the solid foundation of v0.2.0 by +adding polish, efficiency, and advanced features. + +=== UI Improvements + +==== 1. Snapshot Diffing Tool 🔍 + +*Status*: Design Phase + +*Features*: - Visual comparison between two identity snapshots - +Side-by-side panel state comparison - Settings diff with highlighting - +Service URL changes visualization - JSON diff for advanced users + +*UI Components*: + +[source,rescript] +---- +// SnapshotDiffViewer.res +module SnapshotDiffViewer = { + @react.component + let make = (~snapshotA, ~snapshotB, ~onClose) => { + let diff = calculateDiff(snapshotA, snapshotB) + +
+ + + + + + + + + + + + + + + +
+ } +} +---- + +*Implementation Plan*: - [ ] Design diff algorithm (JSON diff + semantic +diff) - [ ] Create React components for diff visualization - [ ] +Integrate with identity management UI - [ ] Add keyboard navigation - [ +] Implement copy/export functionality + +==== 2. Snapshot Tagging System 🏷️ + +*Status*: Planned + +*Features*: - Add tags to identity snapshots - Tag-based filtering and +search - Color-coded tags - Common tag suggestions - Tag management UI + +*Database Schema*: + +[source,typescript] +---- +interface SnapshotTag { + id: string; + name: string; + color: string; // hex color code + created_at: string; +} + +interface SnapshotWithTags extends IdentitySnapshot { + tags: string[]; // tag IDs +} +---- + +*UI Integration*: + +[source,rescript] +---- +// SnapshotTagInput.res +let make = (~snapshot, ~onTagsChange) => { + let (inputValue, setInputValue) = React.useState("") + let (suggestions, setSuggestions) = React.useState([]) + +
+ {snapshot.tags->Belt.Array.map(tag => + + )->React.array} + + { + setInputValue(ev.target.value) + // Fetch tag suggestions + } + onKeyDown=ev => { + if (ev.key === "Enter") { + onTagsChange([...snapshot.tags, inputValue]) + setInputValue("") + } + } + /> + + { + onTagsChange([...snapshot.tags, tag]) + setInputValue("") + } + /> +
+} +---- + +*Implementation Plan*: - [ ] Extend identity snapshot schema with tags - +[ ] Create tag management backend API - [ ] Design tag input component - +[ ] Implement tag suggestions engine - [ ] Add tag filtering to snapshot +list + +=== Performance Optimizations + +==== 3. Performance Caching Layer ⚡ + +*Status*: Planned + +*Strategy*: - *LRU Cache*: Least Recently Used cache for identity +operations - *TTL Cache*: Time-to-live cache for VeriSimDB queries - +*Two-Level Cache*: Memory + persistent cache - *Cache Invalidation*: +Smart invalidation on writes + +*Implementation*: + +[source,rust] +---- +// src-gossamer/src/identity_cache.rs +use std::collections::HashMap; +use lru::LruCache; +use std::sync::{Arc, Mutex}; + +pub struct IdentityCache { + memory_cache: Arc>>, // ID -> JSON + disk_cache: HashMap, // ID -> JSON + cache_ttl: std::time::Duration, +} + +impl IdentityCache { + pub fn new(capacity: usize, ttl: std::time::Duration) -> Self { + Self { + memory_cache: Arc::new(Mutex::new(LruCache::new(capacity))), + disk_cache: HashMap::new(), + cache_ttl: ttl, + } + } + + pub fn get(&self, id: &str) -> Option { + // Check memory cache first + if let Some(data) = self.memory_cache.lock().unwrap().get(id) { + return Some(data.clone()); + } + + // Check disk cache + self.disk_cache.get(id).cloned() + } + + pub fn set(&mut self, id: String, data: String) { + // Update both caches + self.memory_cache.lock().unwrap().put(id.clone(), data.clone()); + self.disk_cache.insert(id, data); + + // Persist to disk periodically + } + + pub fn invalidate(&mut self, id: &str) { + self.memory_cache.lock().unwrap().pop(id); + self.disk_cache.remove(id); + } +} +---- + +*Cache Statistics*: + +[source,json] +---- +{ + "cache_hits": 128, + "cache_misses": 42, + "hit_rate": 0.754, + "memory_usage": "12.4MB", + "disk_usage": "45.2MB", + "average_response_time": "12ms" +} +---- + +*Implementation Plan*: - [ ] Implement LRU cache in Rust - [ ] Add disk +persistence layer - [ ] Integrate with identity operations - [ ] Add +cache statistics monitoring - [ ] Implement cache warming on startup + +==== 4. Batch Operations 🚀 + +*Status*: Planned + +*Features*: - Batch save multiple snapshots - Batch load with parallel +requests - Batch delete operations - Progress tracking - Error handling +for partial failures + +*API Design*: + +[source,typescript] +---- +// Batch operations API +interface BatchOperationResult { + success: T[]; + failures: { id: string; error: string }[]; + summary: { + total: number; + success: number; + failed: number; + duration_ms: number; + }; +} + +// Batch save +async function batchSaveSnapshots( + snapshots: Omit[] +): Promise> { + // Implementation with parallel processing +} + +// Batch load +async function batchLoadSnapshots( + ids: string[] +): Promise> { + // Implementation with parallel requests +} + +// Batch delete +async function batchDeleteSnapshots( + ids: string[] +): Promise> { + // Implementation with transaction support +} +---- + +*Implementation Plan*: - [ ] Design batch operation API - [ ] Implement +parallel request handling - [ ] Add progress tracking - [ ] Implement +transaction support - [ ] Add batch operation UI + +==== 5. Snapshot Compression 🗜️ + +*Status*: Planned + +*Strategy*: - *Gzip Compression*: For JSON payloads - *Size Thresholds*: +Only compress large snapshots (>10KB) - *Transparent*: Automatic +compression/decompression - *Performance*: Benchmark compression ratios +vs. CPU usage + +*Implementation*: + +[source,rust] +---- +// src-gossamer/src/identity.rs +use flate2::write::GzEncoder; +use flate2::read::GzDecoder; +use std::io::Read; + +const COMPRESSION_THRESHOLD: usize = 10_240; // 10KB + +fn compress_snapshot(json: &str) -> Result { + if json.len() < COMPRESSION_THRESHOLD { + return Ok(json.to_string()); + } + + let mut encoder = GzEncoder::new(Vec::new(), flate2::Compression::default()); + encoder.write_all(json.as_bytes()) + .map_err(|e| format!("Compression failed: {}", e))?; + + let compressed = encoder.finish() + .map_err(|e| format!("Compression finish failed: {}", e))?; + + Ok(base64::encode(&compressed)) +} + +fn decompress_snapshot(compressed: &str) -> Result { + let decoded = base64::decode(compressed) + .map_err(|e| format!("Base64 decode failed: {}", e))?; + + let mut decoder = GzDecoder::new(&decoded[..]); + let mut decompressed = String::new(); + decoder.read_to_string(&mut decompressed) + .map_err(|e| format!("Decompression failed: {}", e))?; + + Ok(decompressed) +} +---- + +*Compression Benchmarks*: + +.... +Snapshot Size | Original | Compressed | Ratio | Time +-------------|----------|------------|-------|------ +15KB | 15,360 | 3,204 | 4.8x | 8ms +50KB | 51,200 | 9,872 | 5.2x | 15ms +100KB | 102,400 | 18,432 | 5.6x | 28ms +500KB | 512,000 | 89,056 | 5.8x | 120ms +.... + +*Implementation Plan*: - [ ] Add flate2 dependency to Cargo.toml - [ ] +Implement compression/decompression functions - [ ] Integrate with +identity save/load - [ ] Add compression ratio metrics - [ ] Implement +adaptive compression thresholds + +=== Implementation Roadmap + +==== Phase 1: UI Improvements (2 weeks) + +* Week 1: Snapshot diffing tool design & implementation +* Week 2: Tagging system backend & frontend + +==== Phase 2: Performance (2 weeks) + +* Week 3: Caching layer implementation +* Week 4: Batch operations API & UI + +==== Phase 3: Optimization (1 week) + +* Week 5: Snapshot compression & final testing + +=== Success Metrics + +==== UI Improvements + +* *Snapshot Diffing*: 90% user satisfaction rate +* *Tagging System*: 80% of users add tags to snapshots +* *Discovery*: 30% reduction in snapshot management time + +==== Performance + +* *Cache Hit Rate*: Target 85%+ for identity operations +* *Batch Operations*: 70% time reduction for bulk operations +* *Compression*: 5x average compression ratio for large snapshots +* *Response Times*: <50ms for cached operations, <150ms for uncached + +=== Testing Strategy + +==== New Test Coverage + +* *Diff Algorithm*: Accuracy and performance tests +* *Tagging System*: CRUD operations and edge cases +* *Cache Layer*: Hit/miss ratios, invalidation scenarios +* *Batch Operations*: Partial failure handling, progress tracking +* *Compression*: Round-trip integrity, performance benchmarks + +==== Performance Testing + +* Load testing with 10,000 snapshots +* Cache stress testing +* Batch operation scalability +* Memory usage profiling + +=== Documentation Updates + +==== User Documentation + +* *Snapshot Diffing Guide*: How to compare and merge snapshots +* *Tagging Best Practices*: Effective tagging strategies +* *Performance Tips*: Optimizing large-scale identity management + +==== Developer Documentation + +* *Cache API Reference*: Integration guide for caching layer +* *Batch Operations API*: Usage patterns and examples +* *Compression Internals*: Implementation details and tuning + +=== Backward Compatibility + +==== Breaking Changes + +* *None planned*: All v0.2.1 features are additive + +==== Migration Path + +* *Automatic*: Existing snapshots work without modification +* *Optional*: Users can opt-in to new features +* *Graceful*: Fallback to v0.2.0 behavior if needed + +=== Risk Assessment + +==== High Risk 🔴 + +* *Cache Invalidation*: Complex logic could cause stale data +* *Batch Operations*: Transaction handling complexity +* *Compression*: Data corruption risks with malformed input + +==== Mitigation Strategies + +* *Extensive Testing*: Edge cases and failure scenarios +* *Feature Flags*: Gradual rollout of new features +* *Monitoring*: Real-time metrics and alerts +* *Rollback Plan*: Quick disable of problematic features + +=== Stakeholder Communication + +==== Updates Required + +* *Users*: Feature announcements and tutorials +* *Developers*: API changes and integration guides +* *Testers*: Test plans and regression suites +* *Documentation*: Updated guides and references + +==== Timeline + +* *Design Review*: Week 1 +* *Implementation*: Weeks 2-4 +* *Testing*: Week 5 +* *Release*: Week 6 + +=== Conclusion + +v0.2.1 focuses on making PanLL’s identity management *faster, more +intuitive, and more powerful* while maintaining the stability and +reliability established in v0.2.0. These enhancements will significantly +improve the daily workflow for users working with multiple +configurations and team collaborations. diff --git a/docs/v0.2.1-enhancements.md b/docs/v0.2.1-enhancements.md deleted file mode 100644 index de961975..00000000 --- a/docs/v0.2.1-enhancements.md +++ /dev/null @@ -1,413 +0,0 @@ -# PanLL v0.2.1 Enhancement Plan - -## Overview - -PanLL v0.2.1 focuses on **UI improvements** and **performance optimizations** to enhance the user experience of the Connected Workbench. This release builds on the solid foundation of v0.2.0 by adding polish, efficiency, and advanced features. - -## UI Improvements - -### 1. Snapshot Diffing Tool 🔍 - -**Status**: Design Phase - -**Features**: -- Visual comparison between two identity snapshots -- Side-by-side panel state comparison -- Settings diff with highlighting -- Service URL changes visualization -- JSON diff for advanced users - -**UI Components**: -```rescript -// SnapshotDiffViewer.res -module SnapshotDiffViewer = { - @react.component - let make = (~snapshotA, ~snapshotB, ~onClose) => { - let diff = calculateDiff(snapshotA, snapshotB) - -
- - - - - - - - - - - - - - - -
- } -} -``` - -**Implementation Plan**: -- [ ] Design diff algorithm (JSON diff + semantic diff) -- [ ] Create React components for diff visualization -- [ ] Integrate with identity management UI -- [ ] Add keyboard navigation -- [ ] Implement copy/export functionality - -### 2. Snapshot Tagging System 🏷️ - -**Status**: Planned - -**Features**: -- Add tags to identity snapshots -- Tag-based filtering and search -- Color-coded tags -- Common tag suggestions -- Tag management UI - -**Database Schema**: -```typescript -interface SnapshotTag { - id: string; - name: string; - color: string; // hex color code - created_at: string; -} - -interface SnapshotWithTags extends IdentitySnapshot { - tags: string[]; // tag IDs -} -``` - -**UI Integration**: -```rescript -// SnapshotTagInput.res -let make = (~snapshot, ~onTagsChange) => { - let (inputValue, setInputValue) = React.useState("") - let (suggestions, setSuggestions) = React.useState([]) - -
- {snapshot.tags->Belt.Array.map(tag => - - )->React.array} - - { - setInputValue(ev.target.value) - // Fetch tag suggestions - } - onKeyDown=ev => { - if (ev.key === "Enter") { - onTagsChange([...snapshot.tags, inputValue]) - setInputValue("") - } - } - /> - - { - onTagsChange([...snapshot.tags, tag]) - setInputValue("") - } - /> -
-} -``` - -**Implementation Plan**: -- [ ] Extend identity snapshot schema with tags -- [ ] Create tag management backend API -- [ ] Design tag input component -- [ ] Implement tag suggestions engine -- [ ] Add tag filtering to snapshot list - -## Performance Optimizations - -### 3. Performance Caching Layer ⚡ - -**Status**: Planned - -**Strategy**: -- **LRU Cache**: Least Recently Used cache for identity operations -- **TTL Cache**: Time-to-live cache for VeriSimDB queries -- **Two-Level Cache**: Memory + persistent cache -- **Cache Invalidation**: Smart invalidation on writes - -**Implementation**: -```rust -// src-gossamer/src/identity_cache.rs -use std::collections::HashMap; -use lru::LruCache; -use std::sync::{Arc, Mutex}; - -pub struct IdentityCache { - memory_cache: Arc>>, // ID -> JSON - disk_cache: HashMap, // ID -> JSON - cache_ttl: std::time::Duration, -} - -impl IdentityCache { - pub fn new(capacity: usize, ttl: std::time::Duration) -> Self { - Self { - memory_cache: Arc::new(Mutex::new(LruCache::new(capacity))), - disk_cache: HashMap::new(), - cache_ttl: ttl, - } - } - - pub fn get(&self, id: &str) -> Option { - // Check memory cache first - if let Some(data) = self.memory_cache.lock().unwrap().get(id) { - return Some(data.clone()); - } - - // Check disk cache - self.disk_cache.get(id).cloned() - } - - pub fn set(&mut self, id: String, data: String) { - // Update both caches - self.memory_cache.lock().unwrap().put(id.clone(), data.clone()); - self.disk_cache.insert(id, data); - - // Persist to disk periodically - } - - pub fn invalidate(&mut self, id: &str) { - self.memory_cache.lock().unwrap().pop(id); - self.disk_cache.remove(id); - } -} -``` - -**Cache Statistics**: -```json -{ - "cache_hits": 128, - "cache_misses": 42, - "hit_rate": 0.754, - "memory_usage": "12.4MB", - "disk_usage": "45.2MB", - "average_response_time": "12ms" -} -``` - -**Implementation Plan**: -- [ ] Implement LRU cache in Rust -- [ ] Add disk persistence layer -- [ ] Integrate with identity operations -- [ ] Add cache statistics monitoring -- [ ] Implement cache warming on startup - -### 4. Batch Operations 🚀 - -**Status**: Planned - -**Features**: -- Batch save multiple snapshots -- Batch load with parallel requests -- Batch delete operations -- Progress tracking -- Error handling for partial failures - -**API Design**: -```typescript -// Batch operations API -interface BatchOperationResult { - success: T[]; - failures: { id: string; error: string }[]; - summary: { - total: number; - success: number; - failed: number; - duration_ms: number; - }; -} - -// Batch save -async function batchSaveSnapshots( - snapshots: Omit[] -): Promise> { - // Implementation with parallel processing -} - -// Batch load -async function batchLoadSnapshots( - ids: string[] -): Promise> { - // Implementation with parallel requests -} - -// Batch delete -async function batchDeleteSnapshots( - ids: string[] -): Promise> { - // Implementation with transaction support -} -``` - -**Implementation Plan**: -- [ ] Design batch operation API -- [ ] Implement parallel request handling -- [ ] Add progress tracking -- [ ] Implement transaction support -- [ ] Add batch operation UI - -### 5. Snapshot Compression 🗜️ - -**Status**: Planned - -**Strategy**: -- **Gzip Compression**: For JSON payloads -- **Size Thresholds**: Only compress large snapshots (>10KB) -- **Transparent**: Automatic compression/decompression -- **Performance**: Benchmark compression ratios vs. CPU usage - -**Implementation**: -```rust -// src-gossamer/src/identity.rs -use flate2::write::GzEncoder; -use flate2::read::GzDecoder; -use std::io::Read; - -const COMPRESSION_THRESHOLD: usize = 10_240; // 10KB - -fn compress_snapshot(json: &str) -> Result { - if json.len() < COMPRESSION_THRESHOLD { - return Ok(json.to_string()); - } - - let mut encoder = GzEncoder::new(Vec::new(), flate2::Compression::default()); - encoder.write_all(json.as_bytes()) - .map_err(|e| format!("Compression failed: {}", e))?; - - let compressed = encoder.finish() - .map_err(|e| format!("Compression finish failed: {}", e))?; - - Ok(base64::encode(&compressed)) -} - -fn decompress_snapshot(compressed: &str) -> Result { - let decoded = base64::decode(compressed) - .map_err(|e| format!("Base64 decode failed: {}", e))?; - - let mut decoder = GzDecoder::new(&decoded[..]); - let mut decompressed = String::new(); - decoder.read_to_string(&mut decompressed) - .map_err(|e| format!("Decompression failed: {}", e))?; - - Ok(decompressed) -} -``` - -**Compression Benchmarks**: -``` -Snapshot Size | Original | Compressed | Ratio | Time --------------|----------|------------|-------|------ -15KB | 15,360 | 3,204 | 4.8x | 8ms -50KB | 51,200 | 9,872 | 5.2x | 15ms -100KB | 102,400 | 18,432 | 5.6x | 28ms -500KB | 512,000 | 89,056 | 5.8x | 120ms -``` - -**Implementation Plan**: -- [ ] Add flate2 dependency to Cargo.toml -- [ ] Implement compression/decompression functions -- [ ] Integrate with identity save/load -- [ ] Add compression ratio metrics -- [ ] Implement adaptive compression thresholds - -## Implementation Roadmap - -### Phase 1: UI Improvements (2 weeks) -- Week 1: Snapshot diffing tool design & implementation -- Week 2: Tagging system backend & frontend - -### Phase 2: Performance (2 weeks) -- Week 3: Caching layer implementation -- Week 4: Batch operations API & UI - -### Phase 3: Optimization (1 week) -- Week 5: Snapshot compression & final testing - -## Success Metrics - -### UI Improvements -- **Snapshot Diffing**: 90% user satisfaction rate -- **Tagging System**: 80% of users add tags to snapshots -- **Discovery**: 30% reduction in snapshot management time - -### Performance -- **Cache Hit Rate**: Target 85%+ for identity operations -- **Batch Operations**: 70% time reduction for bulk operations -- **Compression**: 5x average compression ratio for large snapshots -- **Response Times**: <50ms for cached operations, <150ms for uncached - -## Testing Strategy - -### New Test Coverage -- **Diff Algorithm**: Accuracy and performance tests -- **Tagging System**: CRUD operations and edge cases -- **Cache Layer**: Hit/miss ratios, invalidation scenarios -- **Batch Operations**: Partial failure handling, progress tracking -- **Compression**: Round-trip integrity, performance benchmarks - -### Performance Testing -- Load testing with 10,000 snapshots -- Cache stress testing -- Batch operation scalability -- Memory usage profiling - -## Documentation Updates - -### User Documentation -- **Snapshot Diffing Guide**: How to compare and merge snapshots -- **Tagging Best Practices**: Effective tagging strategies -- **Performance Tips**: Optimizing large-scale identity management - -### Developer Documentation -- **Cache API Reference**: Integration guide for caching layer -- **Batch Operations API**: Usage patterns and examples -- **Compression Internals**: Implementation details and tuning - -## Backward Compatibility - -### Breaking Changes -- **None planned**: All v0.2.1 features are additive - -### Migration Path -- **Automatic**: Existing snapshots work without modification -- **Optional**: Users can opt-in to new features -- **Graceful**: Fallback to v0.2.0 behavior if needed - -## Risk Assessment - -### High Risk 🔴 -- **Cache Invalidation**: Complex logic could cause stale data -- **Batch Operations**: Transaction handling complexity -- **Compression**: Data corruption risks with malformed input - -### Mitigation Strategies -- **Extensive Testing**: Edge cases and failure scenarios -- **Feature Flags**: Gradual rollout of new features -- **Monitoring**: Real-time metrics and alerts -- **Rollback Plan**: Quick disable of problematic features - -## Stakeholder Communication - -### Updates Required -- **Users**: Feature announcements and tutorials -- **Developers**: API changes and integration guides -- **Testers**: Test plans and regression suites -- **Documentation**: Updated guides and references - -### Timeline -- **Design Review**: Week 1 -- **Implementation**: Weeks 2-4 -- **Testing**: Week 5 -- **Release**: Week 6 - -## Conclusion - -v0.2.1 focuses on making PanLL's identity management **faster, more intuitive, and more powerful** while maintaining the stability and reliability established in v0.2.0. These enhancements will significantly improve the daily workflow for users working with multiple configurations and team collaborations. \ No newline at end of file diff --git a/llm-warmup-user.adoc b/llm-warmup-user.adoc new file mode 100644 index 00000000..c13529e0 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — rsr-template-repo (User) + +=== What is rsr-template-repo? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.md b/llm-warmup-user.md deleted file mode 100644 index 18a327ef..00000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — rsr-template-repo (User) - -## What is rsr-template-repo? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/migration/modules/STATUS.adoc b/migration/modules/STATUS.adoc new file mode 100644 index 00000000..a318c496 --- /dev/null +++ b/migration/modules/STATUS.adoc @@ -0,0 +1,132 @@ +== `+migration/modules/+` parity status + +Snapshot of the panll `+src/modules/+` ReScript → AffineScript port +(Mode A — compiles). Filed 2026-05-31 as the first compilable migration +batch for panll’s STEP 8 megaport (standards#279). + +=== Parity table + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|.affine file |`+affinescript check+` |Source .res LoC |Notes +|`+ServiceEndpoints.affine+` |✅ passes |39 |Pure constants. + +|`+TsdmModule.affine+` |✅ passes |57 |Capability sum + config record + +helpers. + +|`+TangleVizModule.affine+` |✅ passes |57 |Same shape. + +|`+LanguageForgeModule.affine+` |✅ passes |60 |Same shape. + +|`+PanicAttackModule.affine+` |✅ passes |63 |Same shape. + +|`+FarmModule.affine+` |✅ passes |66 |Same shape + manifestPath field. + +|`+MassPanicModule.affine+` |✅ passes |66 |Same shape + binaryName +field. + +|`+VerificationDashboardModule.affine+` |✅ passes |67 |Same shape. + +|`+SpecBrowserModule.affine+` |✅ passes |68 |Same shape. + +|`+PlazaModule.affine+` |✅ passes |79 |Same shape. + +|`+CloudGuardModule.affine+` |✅ passes |93 |Same shape + +capabilityDescription helper. +|=== + +*Score (2026-05-31): 11 / 11 compile.* Total LoC: 715 lines of source +`+.res+` ported. + +=== What shape this batch was + +All 11 files share a single mechanical pattern: + +.... +type xxxCapability = | A | B | ... +type xxxModuleConfig = { id: ..., name: ..., capabilities: ..., icon: ... } +let config: xxxModuleConfig = { ... } +let hasCapability = (cap) => config.capabilities->Array.includes(cap) +let capabilityLabel = (cap) => switch cap { | A => "...", | B => "..." } +.... + +Mapping to AffineScript: - `+type x = | A | B+` — unchanged shape +(semicolons added) - `+type t = { field: T, ... }+` — unchanged (no +trailing comma) - `+option+` → `+Option+` - `+array+` +→ `+[T]+` - `+let config = { ... }+` → `+const config: T = #{ ... };+` +(AS records need `+#{...}+`) - `+let f = (x: T): U => body+` → +`+fn f(x: T) -> U { body }+` - `+arr->Array.includes(x)+` → +`+contains(arr, x)+` (prelude::contains) - `+switch x { | A => "..." }+` +→ `+match x { A => "...", }+` (no leading `+|+`, comma-separated arms, +no `+=>+` change) + +=== What this PR is NOT + +This does *not* replace any `+src/modules/*.res+` file in the build. The +.res files still own the runtime contract — they compile to +`+src/modules/*.res.mjs+` via the root `+rescript.json+`, which the rest +of panll imports. Replacement requires: + +[arabic] +. AffineScript → ESM codegen for these modules. +. Migration of (or compatibility shim for) the existing consumers — +every place that does `+open FarmModule+`, +`+let cap = TsdmModule.config.capabilities+`, etc. + +Both are separate slices, tracked under standards#279 STEP 8. + +=== What this PR IS + +The 11 `+.affine+` files are the *verified-correct future shape*. When +AS gains source-to-ESM codegen (Deno target already supports this for +stdlib; module-tree support is the gap), promoting these 11 files to +in-build status becomes a one-PR cutover instead of an 11-PR rewrite — +the design risk is already discharged here. + +=== What blocked the _other_ panll subsystems + +These 11 module files were the cleanest port surface in panll. Most of +the other 715 remaining `+.res+` files block on: + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Blocker |Affected subsystem |Effect +|*TEA framework bindings* (Tea_App, Tea_Cmd, Tea_Html, Tea_Sub, +Tea_Vdom, …) |All of `+src/components/+` (126), `+src/update/+` (89), +`+src/view/+`, `+src/App.res+`, `+src/View.res+` |Components / view / +update use `+Tea_*+` modules. Need AffineScript-side TEA bindings before +port. + +|*Gossamer IPC FFI* |`+src/subscriptions/GossamerEvents.res+`, +`+clade-portal/+`, `+src/RuntimeBridge*+` |Need AS Gossamer IPC +bindings. + +|*ReScript JSX* |`+src/components/*+` |View files use JSX. AS has a +different view story; need port plan. + +|*`+Js.*+` interop* |`+src/storage/Storage.res+`, +`+src/SubscriptionsFixed.res+`, `+clade-portal/src/CladeCmd.res+` +(`+JsExn+`) |Need `+use deno::{...}+` equivalents or carve-outs. +|=== + +=== Replacement of `+src/modules/*.res+` + +Once .affine → .mjs codegen lands for non-stdlib modules, the swap is +mechanical (per file): + +[arabic] +. Compile `+.affine+` to `+.res.mjs+`-equivalent. +. Verify consumer modules see identical export names (`+config+`, +`+hasCapability+`, `+capabilityLabel+`, `+capabilityDescription+` where +present). +. Delete the `+.res+` source. +. Run tests. + +The current batch sets up step 1 input (each file passes +`+affinescript check+`); step 2 (consumer compat) needs +naming-convention verification — capability sum names are PascalCase on +both sides (`+FarmCapability+`), but the underlying ReScript convention +used camelCase `+farmCapability+`. Consumers either pattern-match on the +constructors (no problem) or use the type-name as a type annotation +(might need a rename pass; tracked in STATUS as the only known +consumer-port wart). diff --git a/migration/modules/STATUS.md b/migration/modules/STATUS.md deleted file mode 100644 index 6928b499..00000000 --- a/migration/modules/STATUS.md +++ /dev/null @@ -1,81 +0,0 @@ - - - -# `migration/modules/` parity status - -Snapshot of the panll `src/modules/` ReScript → AffineScript port (Mode A — compiles). Filed 2026-05-31 as the first compilable migration batch for panll's STEP 8 megaport (standards#279). - -## Parity table - -| .affine file | `affinescript check` | Source .res LoC | Notes | -|---|---|---|---| -| `ServiceEndpoints.affine` | ✅ passes | 39 | Pure constants. | -| `TsdmModule.affine` | ✅ passes | 57 | Capability sum + config record + helpers. | -| `TangleVizModule.affine` | ✅ passes | 57 | Same shape. | -| `LanguageForgeModule.affine` | ✅ passes | 60 | Same shape. | -| `PanicAttackModule.affine` | ✅ passes | 63 | Same shape. | -| `FarmModule.affine` | ✅ passes | 66 | Same shape + manifestPath field. | -| `MassPanicModule.affine` | ✅ passes | 66 | Same shape + binaryName field. | -| `VerificationDashboardModule.affine` | ✅ passes | 67 | Same shape. | -| `SpecBrowserModule.affine` | ✅ passes | 68 | Same shape. | -| `PlazaModule.affine` | ✅ passes | 79 | Same shape. | -| `CloudGuardModule.affine` | ✅ passes | 93 | Same shape + capabilityDescription helper. | - -**Score (2026-05-31): 11 / 11 compile.** Total LoC: 715 lines of source `.res` ported. - -## What shape this batch was - -All 11 files share a single mechanical pattern: - -``` -type xxxCapability = | A | B | ... -type xxxModuleConfig = { id: ..., name: ..., capabilities: ..., icon: ... } -let config: xxxModuleConfig = { ... } -let hasCapability = (cap) => config.capabilities->Array.includes(cap) -let capabilityLabel = (cap) => switch cap { | A => "...", | B => "..." } -``` - -Mapping to AffineScript: -- `type x = | A | B` — unchanged shape (semicolons added) -- `type t = { field: T, ... }` — unchanged (no trailing comma) -- `option` → `Option` -- `array` → `[T]` -- `let config = { ... }` → `const config: T = #{ ... };` (AS records need `#{...}`) -- `let f = (x: T): U => body` → `fn f(x: T) -> U { body }` -- `arr->Array.includes(x)` → `contains(arr, x)` (prelude::contains) -- `switch x { | A => "..." }` → `match x { A => "...", }` (no leading `|`, comma-separated arms, no `=>` change) - -## What this PR is NOT - -This does **not** replace any `src/modules/*.res` file in the build. The .res files still own the runtime contract — they compile to `src/modules/*.res.mjs` via the root `rescript.json`, which the rest of panll imports. Replacement requires: - -1. AffineScript → ESM codegen for these modules. -2. Migration of (or compatibility shim for) the existing consumers — every place that does `open FarmModule`, `let cap = TsdmModule.config.capabilities`, etc. - -Both are separate slices, tracked under standards#279 STEP 8. - -## What this PR IS - -The 11 `.affine` files are the **verified-correct future shape**. When AS gains source-to-ESM codegen (Deno target already supports this for stdlib; module-tree support is the gap), promoting these 11 files to in-build status becomes a one-PR cutover instead of an 11-PR rewrite — the design risk is already discharged here. - -## What blocked the *other* panll subsystems - -These 11 module files were the cleanest port surface in panll. Most of the other 715 remaining `.res` files block on: - -| Blocker | Affected subsystem | Effect | -|---|---|---| -| **TEA framework bindings** (Tea_App, Tea_Cmd, Tea_Html, Tea_Sub, Tea_Vdom, ...) | All of `src/components/` (126), `src/update/` (89), `src/view/`, `src/App.res`, `src/View.res` | Components / view / update use `Tea_*` modules. Need AffineScript-side TEA bindings before port. | -| **Gossamer IPC FFI** | `src/subscriptions/GossamerEvents.res`, `clade-portal/`, `src/RuntimeBridge*` | Need AS Gossamer IPC bindings. | -| **ReScript JSX** | `src/components/*` | View files use JSX. AS has a different view story; need port plan. | -| **`Js.*` interop** | `src/storage/Storage.res`, `src/SubscriptionsFixed.res`, `clade-portal/src/CladeCmd.res` (`JsExn`) | Need `use deno::{...}` equivalents or carve-outs. | - -## Replacement of `src/modules/*.res` - -Once .affine → .mjs codegen lands for non-stdlib modules, the swap is mechanical (per file): - -1. Compile `.affine` to `.res.mjs`-equivalent. -2. Verify consumer modules see identical export names (`config`, `hasCapability`, `capabilityLabel`, `capabilityDescription` where present). -3. Delete the `.res` source. -4. Run tests. - -The current batch sets up step 1 input (each file passes `affinescript check`); step 2 (consumer compat) needs naming-convention verification — capability sum names are PascalCase on both sides (`FarmCapability`), but the underlying ReScript convention used camelCase `farmCapability`. Consumers either pattern-match on the constructors (no problem) or use the type-name as a type annotation (might need a rename pass; tracked in STATUS as the only known consumer-port wart). diff --git a/panel-clades/ABI-FFI-README.md b/panel-clades/ABI-FFI-README.adoc similarity index 74% rename from panel-clades/ABI-FFI-README.md rename to panel-clades/ABI-FFI-README.adoc index 1a4c2d73..d8ce9cb7 100644 --- a/panel-clades/ABI-FFI-README.md +++ b/panel-clades/ABI-FFI-README.adoc @@ -1,19 +1,22 @@ -{{~ Aditionally delete this line and fill out the template below ~}} +\{\{~ Aditionally delete this line and fill out the template below ~}} -# panel-clades ABI/FFI Documentation +== panel-clades ABI/FFI Documentation -## Overview +=== Overview -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI -## Architecture +=== Architecture -``` +.... ┌─────────────────────────────────────────────┐ │ ABI Definitions (Idris2) │ │ src/abi/ │ @@ -45,11 +48,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, ReScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... {{project}}/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -77,15 +80,17 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ├── rust/ ├── rescript/ └── julia/ -``` +.... -## Why Idris2 for ABI? +=== Why Idris2 for ABI? -### 1. **Formal Verification** +==== 1. *Formal Verification* -Idris2's dependent types allow proving properties about the ABI at compile-time: +Idris2’s dependent types allow proving properties about the ABI at +compile-time: -```idris +[source,idris] +---- -- Prove struct size is correct public export exampleStructSize : HasSize ExampleStruct 16 @@ -97,13 +102,14 @@ fieldAligned : Divides 8 (offsetOf ExampleStruct.field) -- Prove ABI is platform-compatible public export abiCompatible : Compatible (ABI 1) (ABI 2) -``` +---- -### 2. **Type Safety** +==== 2. *Type Safety* Encode invariants that C/Zig cannot express: -```idris +[source,idris] +---- -- Non-null pointer guaranteed at type level data Handle : Type where MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle @@ -111,13 +117,14 @@ data Handle : Type where -- Array with length proof data Buffer : (n : Nat) -> Type where MkBuffer : Vect n Byte -> Buffer n -``` +---- -### 3. **Platform Abstraction** +==== 3. *Platform Abstraction* Platform-specific types with compile-time selection: -```idris +[source,idris] +---- CInt : Platform -> Type CInt Linux = Bits32 CInt Windows = Bits32 @@ -125,13 +132,14 @@ CInt Windows = Bits32 CSize : Platform -> Type CSize Linux = Bits64 CSize Windows = Bits64 -``` +---- -### 4. **Safe Evolution** +==== 4. *Safe Evolution* Prove that new ABI versions are backward-compatible: -```idris +[source,idris] +---- -- Compiler enforces compatibility abiUpgrade : ABI 1 -> ABI 2 abiUpgrade old = MkABI2 { @@ -140,71 +148,78 @@ abiUpgrade old = MkABI2 { -- Can add new fields new_features = defaults } -``` +---- -## Why Zig for FFI? +=== Why Zig for FFI? -### 1. **C ABI Compatibility** +==== 1. *C ABI Compatibility* Zig exports C-compatible functions naturally: -```zig +[source,zig] +---- export fn library_function(param: i32) i32 { return param * 2; } -``` +---- -### 2. **Memory Safety** +==== 2. *Memory Safety* Compile-time safety without runtime overhead: -```zig +[source,zig] +---- // Null check enforced at compile time const handle = init() orelse return error.InitFailed; defer free(handle); -``` +---- -### 3. **Cross-Compilation** +==== 3. *Cross-Compilation* Built-in cross-compilation to any platform: -```bash +[source,bash] +---- zig build -Dtarget=x86_64-linux zig build -Dtarget=aarch64-macos zig build -Dtarget=x86_64-windows -``` +---- -### 4. **Zero Dependencies** +==== 4. *Zero Dependencies* No runtime, no libc required (unless explicitly needed): -```zig +[source,zig] +---- // Minimal binary size pub const lib = @import("std"); // Only includes what you use -``` +---- -## Building +=== Building -### Build FFI Library +==== Build FFI Library -```bash +[source,bash] +---- cd ffi/zig zig build # Build debug zig build -Doptimize=ReleaseFast # Build optimized zig build test # Run tests -``` +---- -### Generate C Header from Idris2 ABI +==== Generate C Header from Idris2 ABI -```bash +[source,bash] +---- cd src/abi idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig # Linux x86_64 @@ -215,13 +230,14 @@ zig build -Dtarget=aarch64-macos # Windows x86_64 zig build -Dtarget=x86_64-windows -``` +---- -## Usage +=== Usage -### From C +==== From C -```c +[source,c] +---- #include "{{project}}.h" int main() { @@ -237,16 +253,19 @@ int main() { {{project}}_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -l{{project}} -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import panel-clades.ABI.Foreign main : IO () @@ -259,11 +278,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "{{project}}")] extern "C" { fn {{project}}_init() -> *mut std::ffi::c_void; @@ -282,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" function init() @@ -312,27 +333,30 @@ try finally cleanup(handle) end -``` +---- -## Testing +=== Testing -### Unit Tests (Zig) +==== Unit Tests (Zig) -```bash +[source,bash] +---- cd ffi/zig zig build test -``` +---- -### Integration Tests +==== Integration Tests -```bash +[source,bash] +---- cd ffi/zig zig build test-integration -``` +---- -### ABI Verification (Idris2) +==== ABI Verification (Idris2) -```idris +[source,idris] +---- -- Compile-time verification %runElab verifyABI @@ -342,44 +366,44 @@ main = do verifyLayoutsCorrect verifyAlignmentsCorrect putStrLn "ABI verification passed" -``` +---- -## Contributing +=== Contributing When modifying the ABI/FFI: -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License MPL-2.0 -## See Also +=== See Also -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/panel-clades/CHANGELOG.adoc b/panel-clades/CHANGELOG.adoc new file mode 100644 index 00000000..ca1c6528 --- /dev/null +++ b/panel-clades/CHANGELOG.adoc @@ -0,0 +1,9 @@ +== Changelog + +All notable changes to this project will be documented in this file. + +The format is based on https://keepachangelog.com/en/1.1.0/[Keep a +Changelog], and this project adheres to +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] diff --git a/panel-clades/CHANGELOG.md b/panel-clades/CHANGELOG.md deleted file mode 100644 index 81094769..00000000 --- a/panel-clades/CHANGELOG.md +++ /dev/null @@ -1,11 +0,0 @@ -# Changelog - -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - - - - -## [Unreleased] diff --git a/panel-clades/CODE_OF_CONDUCT.adoc b/panel-clades/CODE_OF_CONDUCT.adoc new file mode 100644 index 00000000..7fafb70a --- /dev/null +++ b/panel-clades/CODE_OF_CONDUCT.adoc @@ -0,0 +1,338 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +Panll a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, +gender identity and expression, level of experience, education, +socio-economic status, nationality, personal appearance, race, caste, +colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |\{\{CONDUCT_EMAIL}} |Detailed reports, sensitive matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *\{\{RESPONSE_TIME}}* +. The \{\{CONDUCT_TEAM}} will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a \{\{CONDUCT_TEAM}} member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The \{\{CONDUCT_TEAM}} will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* \{\{CONDUCT_EMAIL}} with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different \{\{CONDUCT_TEAM}} member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a https://github.com/hyperpolymath/panll/discussions[Discussion] +(for general questions) +* Email \{\{CONDUCT_EMAIL}} (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/panel-clades/CODE_OF_CONDUCT.md b/panel-clades/CODE_OF_CONDUCT.md deleted file mode 100644 index 2487fd31..00000000 --- a/panel-clades/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,327 +0,0 @@ -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in Panll a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | {{CONDUCT_EMAIL}} | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **{{RESPONSE_TIME}}** -2. The {{CONDUCT_TEAM}} will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a {{CONDUCT_TEAM}} member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The {{CONDUCT_TEAM}} will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** {{CONDUCT_EMAIL}} with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different {{CONDUCT_TEAM}} member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://github.com/hyperpolymath/panll/discussions) (for general questions) -- Email {{CONDUCT_EMAIL}} (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/panel-clades/CONTRIBUTING.adoc b/panel-clades/CONTRIBUTING.adoc new file mode 100644 index 00000000..4d80bfd3 --- /dev/null +++ b/panel-clades/CONTRIBUTING.adoc @@ -0,0 +1,112 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/panll.git cd panll + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create panll-dev toolbox enter panll-dev # Install dependencies +manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +panll/ ├── src/ # Source code (Perimeter 1-2) ├── lib/ # Library code +(Perimeter 1-2) ├── extensions/ # Extensions (Perimeter 2) ├── plugins/ +# Plugins (Perimeter 2) ├── tools/ # Tooling (Perimeter 2) ├── docs/ # +Documentation (Perimeter 3) │ ├── architecture/ # ADRs, specs (Perimeter +2) │ └── proposals/ # RFCs (Perimeter 3) ├── examples/ # Examples +(Perimeter 3) ├── spec/ # Spec tests (Perimeter 3) ├── tests/ # Test +suite (Perimeter 2-3) ├── .machine_readable/ # ALL machine-readable +content (Perimeter 1) │ ├── *.a2ml # State files (STATE, META, +ECOSYSTEM, etc.) │ ├── bot_directives/ # Bot configs │ └── contractiles/ +# Policy contracts (k9, dust, lust, must, trust) ├── .well-known/ # +Protocol files (Perimeter 1-3) ├── .github/ # GitHub config (Perimeter +1) │ ├── ISSUE_TEMPLATE/ │ └── workflows/ ├── CHANGELOG.md ├── +CODE_OF_CONDUCT.md ├── CONTRIBUTING.md # This file ├── GOVERNANCE.md ├── +LICENSE ├── MAINTAINERS.md ├── README.adoc ├── SECURITY.md ├── flake.nix +# Nix flake — fallback (Perimeter 1) ├── guix.scm # Guix package — +primary (Perimeter 1) └── Justfile # Task runner (Perimeter 1) + +.... + +--- + +## How to Contribute + +### Reporting Bugs + +**Before reporting**: +1. Search existing issues +2. Check if it's already fixed in `main` +3. Determine which perimeter the bug affects + +**When reporting**: + +Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: + +- Clear, descriptive title +- Environment details (OS, versions, toolchain) +- Steps to reproduce +- Expected vs actual behaviour +- Logs, screenshots, or minimal reproduction + +### Suggesting Features + +**Before suggesting**: +1. Check the [roadmap](ROADMAP.md) if available +2. Search existing issues and discussions +3. Consider which perimeter the feature belongs to + +**When suggesting**: + +Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: + +- Problem statement (what pain point does this solve?) +- Proposed solution +- Alternatives considered +- Which perimeter this affects + +### Your First Contribution + +Look for issues labelled: + +- [`good first issue`](https://github.com/hyperpolymath/panll/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/panll/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/panll/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/panll/labels/perimeter-3) — Community sandbox scope + +--- + +## Development Workflow + +### Branch Naming +.... + +docs/short-description # Documentation (P3) test/what-added # Test +additions (P3) feat/short-description # New features (P2) +fix/issue-number-description # Bug fixes (P2) refactor/what-changed # +Code improvements (P2) security/what-fixed # Security fixes (P1-2) + +.... + +### Commit Messages + +We follow [Conventional Commits](https://www.conventionalcommits.org/): +.... + +(): + +{empty}[optional body] + +{empty}[optional footer] diff --git a/panel-clades/CONTRIBUTING.md b/panel-clades/CONTRIBUTING.md deleted file mode 100644 index 47eb3170..00000000 --- a/panel-clades/CONTRIBUTING.md +++ /dev/null @@ -1,121 +0,0 @@ -# Clone the repository -git clone https://github.com/hyperpolymath/panll.git -cd panll - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create panll-dev -toolbox enter panll-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -panll/ -├── src/ # Source code (Perimeter 1-2) -├── lib/ # Library code (Perimeter 1-2) -├── extensions/ # Extensions (Perimeter 2) -├── plugins/ # Plugins (Perimeter 2) -├── tools/ # Tooling (Perimeter 2) -├── docs/ # Documentation (Perimeter 3) -│ ├── architecture/ # ADRs, specs (Perimeter 2) -│ └── proposals/ # RFCs (Perimeter 3) -├── examples/ # Examples (Perimeter 3) -├── spec/ # Spec tests (Perimeter 3) -├── tests/ # Test suite (Perimeter 2-3) -├── .machine_readable/ # ALL machine-readable content (Perimeter 1) -│ ├── *.a2ml # State files (STATE, META, ECOSYSTEM, etc.) -│ ├── bot_directives/ # Bot configs -│ └── contractiles/ # Policy contracts (k9, dust, lust, must, trust) -├── .well-known/ # Protocol files (Perimeter 1-3) -├── .github/ # GitHub config (Perimeter 1) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── GOVERNANCE.md -├── LICENSE -├── MAINTAINERS.md -├── README.adoc -├── SECURITY.md -├── flake.nix # Nix flake — fallback (Perimeter 1) -├── guix.scm # Guix package — primary (Perimeter 1) -└── Justfile # Task runner (Perimeter 1) -``` - ---- - -## How to Contribute - -### Reporting Bugs - -**Before reporting**: -1. Search existing issues -2. Check if it's already fixed in `main` -3. Determine which perimeter the bug affects - -**When reporting**: - -Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: - -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour -- Logs, screenshots, or minimal reproduction - -### Suggesting Features - -**Before suggesting**: -1. Check the [roadmap](ROADMAP.md) if available -2. Search existing issues and discussions -3. Consider which perimeter the feature belongs to - -**When suggesting**: - -Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: - -- Problem statement (what pain point does this solve?) -- Proposed solution -- Alternatives considered -- Which perimeter this affects - -### Your First Contribution - -Look for issues labelled: - -- [`good first issue`](https://github.com/hyperpolymath/panll/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/panll/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/panll/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/panll/labels/perimeter-3) — Community sandbox scope - ---- - -## Development Workflow - -### Branch Naming -``` -docs/short-description # Documentation (P3) -test/what-added # Test additions (P3) -feat/short-description # New features (P2) -fix/issue-number-description # Bug fixes (P2) -refactor/what-changed # Code improvements (P2) -security/what-fixed # Security fixes (P1-2) -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): -``` -(): - -[optional body] - -[optional footer] diff --git a/panel-clades/MAINTAINERS.adoc b/panel-clades/MAINTAINERS.adoc index 48d97817..fb7db023 100644 --- a/panel-clades/MAINTAINERS.adoc +++ b/panel-clades/MAINTAINERS.adoc @@ -1,47 +1,42 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Maintainers -:toc: preamble +== Maintainers -This document lists the maintainers of this project and their responsibilities. +This document lists the current and former maintainers of *Panll*. -== Current Maintainers +''''' -[cols="2,3,2",options="header"] -|=== -| Name | Role | Contact +=== Current Maintainers -| Jonathan D.A. Jewell -| Lead Maintainer -| https://github.com/hyperpolymath[@hyperpolymath] +[width="100%",cols="24%,29%,22%,25%",options="header",] +|=== +|Name |GitHub |Role |Since +|Jonathan D.A. Jewell |https://github.com/hyperpolymath[@hyperpolymath] +|BDFL |2026-03-16 |=== -== Responsibilities - -Maintainers are responsible for: - -* Reviewing and merging pull requests -* Triaging issues and feature requests -* Ensuring code quality and security standards -* Managing releases and versioning -* Upholding the project's code of conduct +''''' -== Becoming a Maintainer +=== How to Become a Maintainer -Contributors who demonstrate: +Contributors who demonstrate sustained, high-quality contributions and a +solid understanding of the project’s standards and goals may be +nominated to become maintainers. The full criteria and process are +described in GOVERNANCE.md. If you are interested, the best path is to +start contributing consistently and engage constructively in issues and +code reviews. -* Consistent, high-quality contributions -* Understanding of the project's goals and standards -* Constructive participation in discussions -* Commitment to the project's long-term health +''''' -May be invited to become maintainers at the discretion of existing maintainers. +=== Emeritus -== Decision Making +Former maintainers who have stepped back from active maintenance. We are +grateful for their contributions. -* Routine decisions (bug fixes, minor improvements) can be made by any maintainer -* Significant changes require discussion and consensus among maintainers -* Breaking changes or major features should be discussed in issues before implementation +[cols=",,,",options="header",] +|=== +|Name |GitHub |Role |Active +|_None yet_ | | | +|=== -== Contact +''''' -For questions about project governance, open an issue or contact the maintainers listed above. +Copyright (c) 2026 hyperpolymath. Licensed under MPL-2.0. diff --git a/panel-clades/MAINTAINERS.md b/panel-clades/MAINTAINERS.md deleted file mode 100644 index 2a2b3c88..00000000 --- a/panel-clades/MAINTAINERS.md +++ /dev/null @@ -1,38 +0,0 @@ - - -# Maintainers - -This document lists the current and former maintainers of **Panll**. - ---- - -## Current Maintainers - -| Name | GitHub | Role | Since | -|------|--------|------|-------| -| Jonathan D.A. Jewell | [@hyperpolymath](https://github.com/hyperpolymath) | BDFL | 2026-03-16 | - ---- - -## How to Become a Maintainer - -Contributors who demonstrate sustained, high-quality contributions and a solid -understanding of the project's standards and goals may be nominated to become -maintainers. The full criteria and process are described in -[GOVERNANCE.md](GOVERNANCE.md). If you are interested, the best path is to start -contributing consistently and engage constructively in issues and code reviews. - ---- - -## Emeritus - -Former maintainers who have stepped back from active maintenance. We are grateful -for their contributions. - -| Name | GitHub | Role | Active | -|------|--------|------|--------| -| *None yet* | | | | - ---- - -Copyright (c) 2026 hyperpolymath. Licensed under MPL-2.0. diff --git a/panel-clades/PLACEHOLDERS.adoc b/panel-clades/PLACEHOLDERS.adoc new file mode 100644 index 00000000..6bae74d5 --- /dev/null +++ b/panel-clades/PLACEHOLDERS.adoc @@ -0,0 +1,218 @@ +== Template Placeholders + +All placeholders in this template follow the `+panel-clades+` pattern. +After cloning, replace them with your project-specific values. + +=== Recommended: Interactive Bootstrap + +[source,bash] +---- +just init +---- + +This interactively prompts for all values, replaces every placeholder, +validates the result, and runs k9-svc checks if available. + +=== Manual Replace + +[source,bash] +---- +# If you prefer manual replacement (run from repo root) + +sed -i 's/Jonathan D.A. Jewell/Jane Doe/g' $(grep -rl 'Jonathan D.A. Jewell' .) +sed -i 's/j.d.a.jewell@open.ac.uk/jane@example.org/g' $(grep -rl 'j.d.a.jewell@open.ac.uk' .) +sed -i 's/hyperpolymath/my-org/g' $(grep -rl 'hyperpolymath' .) +sed -i 's/Panll/my-project/g' $(grep -rl 'Panll' .) +sed -i 's/panel-clades/MY_PROJECT/g' $(grep -rl 'panel-clades' .) +sed -i 's/{{project}}/my_project/g' $(grep -rl '{{project}}' .) +sed -i 's/panll/my-project/g' $(grep -rl 'panll' .) +sed -i 's/github.com/github.com/g' $(grep -rl 'github.com' .) +sed -i "s/2026/$(date +%Y)/g" $(grep -rl '2026' .) +sed -i "s/2026-03-16/$(date +%Y-%m-%d)/g" $(grep -rl '2026-03-16' .) +---- + +=== Placeholder Reference + +==== Author & Copyright + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+Jonathan D.A. Jewell+` |Full legal name |`+Jane Doe+` |SPDX headers +(all files), MAINTAINERS.md, .mailmap, .reuse/dep5, +docs/AI-CONVENTIONS.md + +|`+j.d.a.jewell@open.ac.uk+` |Primary contact email +|`+jane@example.org+` |SPDX headers (all files), .mailmap, .reuse/dep5, +.well-known/humans.txt + +|`+{{AUTHOR_EMAIL_ALT}}+` |Previous/secondary email (for .mailmap) +|`+old@example.com+` |.mailmap + +|`+{{AUTHOR_ORG}}+` |Author’s organization/affiliation +|`+Acme University+` |project-metadata.k9.ncl + +|`+Jewell+` |Author surname (for citations) |`+Doe+` +|docs/CITATIONS.adoc + +|`+Jonathan+` |Author first name (for citations) |`+Jane+` +|docs/CITATIONS.adoc + +|`+J.D.A.+` |Author initials (for citations) |`+J.+` +|docs/CITATIONS.adoc +|=== + +==== Project Identity + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+Panll+` |Human-readable project name |`+My Project+` |SECURITY.md, +CODE_OF_CONDUCT.md, TOPOLOGY.md, STATE.a2ml, Justfile, GOVERNANCE.md, +MAINTAINERS.md, flake.nix, devcontainer.json + +|`+panel-clades+` |One-line description |`+A tool for X+` |flake.nix + +|`+panel-clades+` |Uppercase identifier (for Idris2 modules, C macros) +|`+MY_PROJECT+` |ABI-FFI-README.md, src/abi/_.idr, ffi/zig/_.zig + +|`+{{project}}+` |Lowercase identifier (for C symbols, filenames) +|`+my_project+` |ABI-FFI-README.md, ffi/zig/*.zig + +|`+panll+` |Repository name (slug) |`+my-project+` |CONTRIBUTING.md, +SECURITY.md, CODE_OF_CONDUCT.md, cliff.toml + +|`+hyperpolymath+` |GitHub/GitLab org or username |`+my-org+` |SPDX +headers, CONTRIBUTING.md, SECURITY.md, GOVERNANCE.md, MAINTAINERS.md, +CODEOWNERS, mirror.yml, cliff.toml + +|`+github.com+` |Git forge domain |`+github.com+` |CONTRIBUTING.md +|=== + +==== Dates + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+2026+` |Current year |`+2026+` |SPDX headers (all files), +GOVERNANCE.md, MAINTAINERS.md + +|`+2026-03-16+` |Current date (ISO) |`+2026-02-14+` |STATE.a2ml, +MAINTAINERS.md + +|`+2026-03-16+` |Last updated date |`+2026-02-14+` |TOPOLOGY.md, +THREAT-MODEL.md +|=== + +==== Contact & Security + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+6759885+hyperpolymath@users.noreply.github.com+` |Security contact +email |`+security@example.org+` |SECURITY.md + +|`+[PGP fingerprint not set]+` |40-char PGP fingerprint +|`+ABCD 1234 ...+` |SECURITY.md + +|`+{{PGP_KEY_URL}}+` |URL to public PGP key +|`+https://keys.openpgp.org/...+` |SECURITY.md + +|`+{{WEBSITE}}+` |Project website |`+https://example.org+` |SECURITY.md + +|`+{{CONDUCT_EMAIL}}+` |Conduct reports email |`+conduct@example.org+` +|CODE_OF_CONDUCT.md + +|`+{{CONDUCT_TEAM}}+` |Conduct committee name +|`+Code of Conduct Committee+` |CODE_OF_CONDUCT.md + +|`+{{RESPONSE_TIME}}+` |SLA for initial response |`+48 hours+` +|CODE_OF_CONDUCT.md +|=== + +==== Git + +[cols=",,,",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+main+` |Main branch name |`+main+` |CONTRIBUTING.md +|=== + +==== Build + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+MPL-2.0+` |License name |`+MPL-2.0+` |ABI-FFI-README.md + +|`+panel-clades+` |One-line project description +|`+FFI bridges between languages+` |STATE.a2ml +|=== + +==== AI Manifest + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+[YOUR-REPO-NAME]+` |Repository name |`+my-project+` +|0-AI-MANIFEST.a2ml + +|`+[DATE]+` |Creation date |`+2026-02-14+` |0-AI-MANIFEST.a2ml + +|`+[YOUR-NAME/ORG]+` |Maintainer name |`+hyperpolymath+` +|0-AI-MANIFEST.a2ml +|=== + +==== AI Installation Guide + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Marker |Description |Files +|`+[TODO-AI-INSTALL]+` |Unfilled section in AI installation guide +|`+docs/AI_INSTALLATION_GUIDE.adoc+`, +`+docs/AI-INSTALL-README-SECTION.adoc+`, `+README.adoc+` +|=== + +These are *not* standard `+panel-clades+` markers – they are TODO +markers that must be replaced with project-specific content before +release. They mark sections where the developer (or AI) must fill in: + +* What questions the AI should ask the user +* Exact prerequisite check and install commands +* Privacy notice specific to this project +* Complete installation command block +* Credential setup instructions (URLs, scopes, env vars) +* Verification commands and expected output +* Error handling table +* Example conversation + +*finishbot checks:* `+just validate-ai-install+` verifies no +`+[TODO-AI-INSTALL]+` markers remain. + +=== Deletion Markers + +Some files contain deletion instructions: + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Marker |Meaning |File +|`+{{~ ... ~}}+` |Delete this entire line after reading +|ABI-FFI-README.md (line 1) +|=== + +=== Verification + +After replacing all placeholders, verify none remain: + +[source,bash] +---- +grep -rn '{{' . --include='*.md' --include='*.adoc' --include='*.a2ml' \ + --include='*.scm' --include='*.idr' --include='*.zig' --include='*.res' \ + --include='Justfile' --include='*.nix' --include='*.toml' --include='*.yml' \ + --include='*.yaml' --include='*.hs' --include='*.ncl' --include='*.txt' \ + --include='*.json' --include='Containerfile' --include='dep5' \ + | grep -v 'PLACEHOLDERS.md' | grep -v 'node_modules' +---- + +If the above command produces no output, all placeholders have been +replaced. diff --git a/panel-clades/PLACEHOLDERS.md b/panel-clades/PLACEHOLDERS.md deleted file mode 100644 index 57dd4ac2..00000000 --- a/panel-clades/PLACEHOLDERS.md +++ /dev/null @@ -1,141 +0,0 @@ -# Template Placeholders - -All placeholders in this template follow the `panel-clades` pattern. -After cloning, replace them with your project-specific values. - -## Recommended: Interactive Bootstrap - -```bash -just init -``` - -This interactively prompts for all values, replaces every placeholder, -validates the result, and runs k9-svc checks if available. - -## Manual Replace - -```bash -# If you prefer manual replacement (run from repo root) - -sed -i 's/Jonathan D.A. Jewell/Jane Doe/g' $(grep -rl 'Jonathan D.A. Jewell' .) -sed -i 's/j.d.a.jewell@open.ac.uk/jane@example.org/g' $(grep -rl 'j.d.a.jewell@open.ac.uk' .) -sed -i 's/hyperpolymath/my-org/g' $(grep -rl 'hyperpolymath' .) -sed -i 's/Panll/my-project/g' $(grep -rl 'Panll' .) -sed -i 's/panel-clades/MY_PROJECT/g' $(grep -rl 'panel-clades' .) -sed -i 's/{{project}}/my_project/g' $(grep -rl '{{project}}' .) -sed -i 's/panll/my-project/g' $(grep -rl 'panll' .) -sed -i 's/github.com/github.com/g' $(grep -rl 'github.com' .) -sed -i "s/2026/$(date +%Y)/g" $(grep -rl '2026' .) -sed -i "s/2026-03-16/$(date +%Y-%m-%d)/g" $(grep -rl '2026-03-16' .) -``` - -## Placeholder Reference - -### Author & Copyright - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `Jonathan D.A. Jewell` | Full legal name | `Jane Doe` | SPDX headers (all files), MAINTAINERS.md, .mailmap, .reuse/dep5, docs/AI-CONVENTIONS.md | -| `j.d.a.jewell@open.ac.uk` | Primary contact email | `jane@example.org` | SPDX headers (all files), .mailmap, .reuse/dep5, .well-known/humans.txt | -| `{{AUTHOR_EMAIL_ALT}}` | Previous/secondary email (for .mailmap) | `old@example.com` | .mailmap | -| `{{AUTHOR_ORG}}` | Author's organization/affiliation | `Acme University` | project-metadata.k9.ncl | -| `Jewell` | Author surname (for citations) | `Doe` | docs/CITATIONS.adoc | -| `Jonathan` | Author first name (for citations) | `Jane` | docs/CITATIONS.adoc | -| `J.D.A.` | Author initials (for citations) | `J.` | docs/CITATIONS.adoc | - -### Project Identity - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `Panll` | Human-readable project name | `My Project` | SECURITY.md, CODE_OF_CONDUCT.md, TOPOLOGY.md, STATE.a2ml, Justfile, GOVERNANCE.md, MAINTAINERS.md, flake.nix, devcontainer.json | -| `panel-clades` | One-line description | `A tool for X` | flake.nix | -| `panel-clades` | Uppercase identifier (for Idris2 modules, C macros) | `MY_PROJECT` | ABI-FFI-README.md, src/abi/*.idr, ffi/zig/*.zig | -| `{{project}}` | Lowercase identifier (for C symbols, filenames) | `my_project` | ABI-FFI-README.md, ffi/zig/*.zig | -| `panll` | Repository name (slug) | `my-project` | CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md, cliff.toml | -| `hyperpolymath` | GitHub/GitLab org or username | `my-org` | SPDX headers, CONTRIBUTING.md, SECURITY.md, GOVERNANCE.md, MAINTAINERS.md, CODEOWNERS, mirror.yml, cliff.toml | -| `github.com` | Git forge domain | `github.com` | CONTRIBUTING.md | - -### Dates - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `2026` | Current year | `2026` | SPDX headers (all files), GOVERNANCE.md, MAINTAINERS.md | -| `2026-03-16` | Current date (ISO) | `2026-02-14` | STATE.a2ml, MAINTAINERS.md | -| `2026-03-16` | Last updated date | `2026-02-14` | TOPOLOGY.md, THREAT-MODEL.md | - -### Contact & Security - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `6759885+hyperpolymath@users.noreply.github.com` | Security contact email | `security@example.org` | SECURITY.md | -| `[PGP fingerprint not set]` | 40-char PGP fingerprint | `ABCD 1234 ...` | SECURITY.md | -| `{{PGP_KEY_URL}}` | URL to public PGP key | `https://keys.openpgp.org/...` | SECURITY.md | -| `{{WEBSITE}}` | Project website | `https://example.org` | SECURITY.md | -| `{{CONDUCT_EMAIL}}` | Conduct reports email | `conduct@example.org` | CODE_OF_CONDUCT.md | -| `{{CONDUCT_TEAM}}` | Conduct committee name | `Code of Conduct Committee` | CODE_OF_CONDUCT.md | -| `{{RESPONSE_TIME}}` | SLA for initial response | `48 hours` | CODE_OF_CONDUCT.md | - -### Git - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `main` | Main branch name | `main` | CONTRIBUTING.md | - -### Build - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `MPL-2.0` | License name | `MPL-2.0` | ABI-FFI-README.md | -| `panel-clades` | One-line project description | `FFI bridges between languages` | STATE.a2ml | - -### AI Manifest - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `[YOUR-REPO-NAME]` | Repository name | `my-project` | 0-AI-MANIFEST.a2ml | -| `[DATE]` | Creation date | `2026-02-14` | 0-AI-MANIFEST.a2ml | -| `[YOUR-NAME/ORG]` | Maintainer name | `hyperpolymath` | 0-AI-MANIFEST.a2ml | - -### AI Installation Guide - -| Marker | Description | Files | -|---|---|---| -| `[TODO-AI-INSTALL]` | Unfilled section in AI installation guide | `docs/AI_INSTALLATION_GUIDE.adoc`, `docs/AI-INSTALL-README-SECTION.adoc`, `README.adoc` | - -These are **not** standard `panel-clades` markers -- they are TODO markers -that must be replaced with project-specific content before release. They mark -sections where the developer (or AI) must fill in: - -- What questions the AI should ask the user -- Exact prerequisite check and install commands -- Privacy notice specific to this project -- Complete installation command block -- Credential setup instructions (URLs, scopes, env vars) -- Verification commands and expected output -- Error handling table -- Example conversation - -**finishbot checks:** `just validate-ai-install` verifies no `[TODO-AI-INSTALL]` markers remain. - -## Deletion Markers - -Some files contain deletion instructions: - -| Marker | Meaning | File | -|---|---|---| -| `{{~ ... ~}}` | Delete this entire line after reading | ABI-FFI-README.md (line 1) | - -## Verification - -After replacing all placeholders, verify none remain: - -```bash -grep -rn '{{' . --include='*.md' --include='*.adoc' --include='*.a2ml' \ - --include='*.scm' --include='*.idr' --include='*.zig' --include='*.res' \ - --include='Justfile' --include='*.nix' --include='*.toml' --include='*.yml' \ - --include='*.yaml' --include='*.hs' --include='*.ncl' --include='*.txt' \ - --include='*.json' --include='Containerfile' --include='dep5' \ - | grep -v 'PLACEHOLDERS.md' | grep -v 'node_modules' -``` - -If the above command produces no output, all placeholders have been replaced. diff --git a/panel-clades/SECURITY.adoc b/panel-clades/SECURITY.adoc new file mode 100644 index 00000000..01fec107 --- /dev/null +++ b/panel-clades/SECURITY.adoc @@ -0,0 +1,451 @@ +== Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. + +=== Table of Contents + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/hyperpolymath/panll/security/advisories/new[Report a +Vulnerability] +. Click *"`Report a vulnerability`"* +. Complete the form with as much detail as possible +. Submit — we’ll receive a private notification + +This method ensures: + +* End-to-end encryption of your report +* Private discussion space for collaboration +* Coordinated disclosure tooling +* Automatic credit when the advisory is published + +==== Alternative: Encrypted Email + +If you cannot use GitHub Security Advisories, you may email us directly: + +[width="100%",cols="50%,50%",] +|=== +|*Email* |6759885+hyperpolymath@users.noreply.github.com +|*PGP Key* |https://hyperpolymath.github.io/pgp.asc[Download Public Key] +|*Fingerprint* |`+TBD+` +|=== + +[source,bash] +---- +# Import our PGP key +curl -sSL https://hyperpolymath.github.io/pgp.asc | gpg --import + +# Verify fingerprint +gpg --fingerprint 6759885+hyperpolymath@users.noreply.github.com + +# Encrypt your report +gpg --armor --encrypt --recipient 6759885+hyperpolymath@users.noreply.github.com report.txt +---- + +____ +*⚠️ Important:* Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. +____ + +''''' + +=== What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. + +==== Required Information + +* *Description*: Clear explanation of the vulnerability +* *Impact*: What an attacker could achieve (confidentiality, integrity, +availability) +* *Affected versions*: Which versions/commits are affected +* *Reproduction steps*: Detailed steps to reproduce the issue + +==== Helpful Additional Information + +* *Proof of concept*: Code, scripts, or screenshots demonstrating the +vulnerability +* *Attack scenario*: Realistic attack scenario showing exploitability +* *CVSS score*: Your assessment of severity (use +https://www.first.org/cvss/calculator/3.1[CVSS 3.1 Calculator]) +* *CWE ID*: Common Weakness Enumeration identifier if known +* *Suggested fix*: If you have ideas for remediation +* *References*: Links to related vulnerabilities, research, or +advisories + +==== Example Report Structure + +[source,markdown] +---- +## Summary +[One-sentence description of the vulnerability] + +## Vulnerability Type +[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +## Affected Component +[File path, function name, API endpoint, etc.] + +## Affected Versions +[Version range or specific commits] + +## Severity Assessment +- CVSS 3.1 Score: [X.X] +- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +## Description +[Detailed technical description] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [...] + +## Proof of Concept +[Code, curl commands, screenshots, etc.] + +## Impact +[What can an attacker achieve?] + +## Suggested Remediation +[Optional: your ideas for fixing] + +## References +[Links to related issues, CVEs, research] +---- + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +____ +*Note:* These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. +____ + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +==== Our Commitments + +* We will not take legal action against researchers who follow this +policy +* We will work with you to understand and resolve the issue +* We will credit you in the security advisory (unless you prefer +anonymity) +* We will notify you before public disclosure +* We will publish advisories with sufficient detail for users to assess +risk + +==== Your Commitments + +* Report vulnerabilities promptly after discovery +* Give us reasonable time to address the issue before disclosure +* Do not access, modify, or delete data beyond what’s necessary to +demonstrate the vulnerability +* Do not degrade service availability (no DoS testing on production) +* Do not share vulnerability details with others until coordinated +disclosure + +==== Disclosure Timeline + +.... +Day 0 You report vulnerability +Day 1-2 We acknowledge receipt +Day 7 We confirm vulnerability and share initial assessment +Day 7-90 We develop and test fix +Day 90 Coordinated public disclosure + (earlier if fix is ready; later by mutual agreement) +.... + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +''''' + +=== Scope + +==== In Scope ✅ + +The following are within scope for security research: + +* This repository (`+hyperpolymath/panll+`) and all its code +* Official releases and packages published from this repository +* Documentation that could lead to security issues +* Build and deployment configurations in this repository +* Dependencies (report here, we’ll coordinate with upstream) + +==== Out of Scope ❌ + +The following are *not* in scope: + +* Third-party services we integrate with (report directly to them) +* Social engineering attacks against maintainers +* Physical security +* Denial of service attacks against production infrastructure +* Spam, phishing, or other non-technical attacks +* Issues already reported or publicly known +* Theoretical vulnerabilities without proof of concept + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* Cryptographic weaknesses +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws + +==== Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +* Missing security headers on non-sensitive pages +* Clickjacking on pages without sensitive actions +* Self-XSS (requires victim to paste code) +* Missing rate limiting (unless it enables a specific attack) +* Username/email enumeration (unless high-risk context) +* Missing cookie flags on non-sensitive cookies +* Software version disclosure +* Verbose error messages (unless exposing secrets) +* Best practice deviations without demonstrable impact + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +If you conduct security research in accordance with this policy: + +* ✅ We will not initiate legal action against you +* ✅ We will not report your activity to law enforcement +* ✅ We will work with you in good faith to resolve issues +* ✅ We consider your research authorised under the Computer Fraud and +Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +* ✅ We waive any potential claim against you for circumvention of +security controls + +==== Good Faith Requirements + +To qualify for safe harbour, you must: + +* Comply with this security policy +* Report vulnerabilities promptly +* Avoid privacy violations (do not access others’ data) +* Avoid service degradation (no destructive testing) +* Not exploit vulnerabilities beyond proof-of-concept +* Not use vulnerabilities for profit (beyond bug bounties where offered) + +____ +*⚠️ Important:* This safe harbour does not extend to third-party +systems. Always check their policies before testing. +____ + +''''' + +=== Recognition + +We believe in recognising security researchers who help us improve. + +==== Hall of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +link:SECURITY-ACKNOWLEDGMENTS.md[Security Acknowledgments] (unless they +prefer anonymity). + +Recognition includes: + +* Your name (or chosen alias) +* Link to your website/profile (optional) +* Brief description of the vulnerability class +* Date of report + +==== What We Offer + +* ✅ Public credit in security advisories +* ✅ Acknowledgment in release notes +* ✅ Entry in our Hall of Fame +* ✅ Reference/recommendation letter upon request (for significant +findings) + +==== What We Don’t Currently Offer + +* ❌ Monetary bug bounties +* ❌ Hardware or swag +* ❌ Paid security research contracts + +____ +*Note:* We’re a community project with limited resources. Your +contributions help everyone who uses this software. +____ + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → Select +"`Security alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/hyperpolymath/panll/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|Severity |Response +|*Critical/High* |Patch release as soon as fix is ready +|*Medium* |Included in next scheduled release (or earlier) +|*Low* |Included in next scheduled release +|=== + +==== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Supported |Notes +|`+main+` branch |✅ Yes |Latest development +|Latest release |✅ Yes |Current stable +|Previous minor release |✅ Yes |Security fixes backported +|Older versions |❌ No |Please upgrade +|=== + +''''' + +=== Security Best Practices + +When using Panll, we recommend: + +==== General + +* Keep dependencies up to date +* Use the latest stable release +* Subscribe to security notifications +* Review configuration against security documentation +* Follow principle of least privilege + +==== For Contributors + +* Never commit secrets, credentials, or API keys +* Use signed commits (`+git config commit.gpgsign true+`) +* Review dependencies before adding them +* Run security linters locally before pushing +* Report any concerns about existing code + +''''' + +=== Additional Resources + +* link:%7B%7BPGP_KEY_URL%7D%7D[Our PGP Public Key] +* https://github.com/hyperpolymath/panll/security/advisories[Security +Advisories] +* link:CHANGELOG.md[Changelog] +* link:CONTRIBUTING.md[Contributing Guidelines] +* https://cve.mitre.org/[CVE Database] +* https://www.first.org/cvss/calculator/3.1[CVSS Calculator] + +''''' + +=== Contact + +[width="100%",cols="50%,50%",options="header",] +|=== +|Purpose |Contact +|*Security issues* +|https://github.com/hyperpolymath/panll/security/advisories/new[Report +via GitHub] or 6759885+hyperpolymath@users.noreply.github.com + +|*General questions* +|https://github.com/hyperpolymath/panll/discussions[GitHub Discussions] + +|*Other enquiries* |See link:README.md[README] for contact information +|=== + +''''' + +=== Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +* Committed to this repository with a clear commit message +* Noted in the changelog +* Announced via GitHub Discussions (for major changes) + +''''' + +_Thank you for helping keep Panll and its users safe._ 🛡️ + +''''' + +Last updated: 2026 · Policy version: 1.0.0 diff --git a/panel-clades/SECURITY.md b/panel-clades/SECURITY.md deleted file mode 100644 index ab5551a1..00000000 --- a/panel-clades/SECURITY.md +++ /dev/null @@ -1,388 +0,0 @@ -# Security Policy - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. - -## Table of Contents - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/hyperpolymath/panll/security/advisories/new) -2. Click **"Report a vulnerability"** -3. Complete the form with as much detail as possible -4. Submit — we'll receive a private notification - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- Coordinated disclosure tooling -- Automatic credit when the advisory is published - -### Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: - -| | | -|---|---| -| **Email** | 6759885+hyperpolymath@users.noreply.github.com | -| **PGP Key** | [Download Public Key](https://hyperpolymath.github.io/pgp.asc) | -| **Fingerprint** | `TBD` | - -```bash -# Import our PGP key -curl -sSL https://hyperpolymath.github.io/pgp.asc | gpg --import - -# Verify fingerprint -gpg --fingerprint 6759885+hyperpolymath@users.noreply.github.com - -# Encrypt your report -gpg --armor --encrypt --recipient 6759885+hyperpolymath@users.noreply.github.com report.txt -``` - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`hyperpolymath/panll`) and all its code -- Official releases and packages published from this repository -- Documentation that could lead to security issues -- Build and deployment configurations in this repository -- Dependencies (report here, we'll coordinate with upstream) - -### Out of Scope ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -If you conduct security research in accordance with this policy: - -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -- ✅ We waive any potential claim against you for circumvention of security controls - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- Not exploit vulnerabilities beyond proof-of-concept -- Not use vulnerabilities for profit (beyond bug bounties where offered) - -> **⚠️ Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. - ---- - -## Recognition - -We believe in recognising security researchers who help us improve. - -### Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our [Security Acknowledgments](SECURITY-ACKNOWLEDGMENTS.md) (unless they prefer anonymity). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### What We Offer - -- ✅ Public credit in security advisories -- ✅ Acknowledgment in release notes -- ✅ Entry in our Hall of Fame -- ✅ Reference/recommendation letter upon request (for significant findings) - -### What We Don't Currently Offer - -- ❌ Monetary bug bounties -- ❌ Hardware or swag -- ❌ Paid security research contracts - -> **Note:** We're a community project with limited resources. Your contributions help everyone who uses this software. - ---- - -## Security Updates - -### Receiving Updates - -To stay informed about security updates: - -- **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/hyperpolymath/panll/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### Supported Versions - - - -| Version | Supported | Notes | -|---------|-----------|-------| -| `main` branch | ✅ Yes | Latest development | -| Latest release | ✅ Yes | Current stable | -| Previous minor release | ✅ Yes | Security fixes backported | -| Older versions | ❌ No | Please upgrade | - ---- - -## Security Best Practices - -When using Panll, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code - ---- - -## Additional Resources - -- [Our PGP Public Key]({{PGP_KEY_URL}}) -- [Security Advisories](https://github.com/hyperpolymath/panll/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/hyperpolymath/panll/security/advisories/new) or 6759885+hyperpolymath@users.noreply.github.com | -| **General questions** | [GitHub Discussions](https://github.com/hyperpolymath/panll/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | - ---- - -## Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - -- Committed to this repository with a clear commit message -- Noted in the changelog -- Announced via GitHub Discussions (for major changes) - ---- - -*Thank you for helping keep Panll and its users safe.* 🛡️ - ---- - -Last updated: 2026 · Policy version: 1.0.0 diff --git a/panel-clades/TOPOLOGY.md b/panel-clades/TOPOLOGY.adoc similarity index 92% rename from panel-clades/TOPOLOGY.md rename to panel-clades/TOPOLOGY.adoc index 63b87347..3291d609 100644 --- a/panel-clades/TOPOLOGY.md +++ b/panel-clades/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== RSR Template Repo — Project Topology -# RSR Template Repo — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ NEW REPOSITORY │ │ (Consumer of this Template) │ @@ -53,11 +49,11 @@ │ Justfile / Mustfile .machine_readable/ │ │ Codeowners / Reuse 0-AI-MANIFEST.a2ml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE STANDARDS @@ -89,11 +85,11 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ██████████ 100% RSR Template Stable & Certified -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Philosophy ──────► RSR Standard ──────► Template Scaffolding ──► New Repo │ │ │ │ ▼ ▼ ▼ ▼ @@ -109,16 +105,17 @@ CCCP Policy ─────► 0-AI-MANIFEST ────────► Justfil │ ▼ k9-svc deploy -``` +.... -## Update Protocol +=== Update Protocol This file is maintained by both humans and AI agents. When updating: -1. **After completing a component**: Change its bar and percentage -2. **After adding a component**: Add a new row in the appropriate section -3. **After architectural changes**: Update the ASCII diagram -4. **Date**: Update the `Last updated` comment at the top of this file +[arabic] +. *After completing a component*: Change its bar and percentage +. *After adding a component*: Add a new row in the appropriate section +. *After architectural changes*: Update the ASCII diagram +. *Date*: Update the `+Last updated+` comment at the top of this file -Progress bars use: `█` (filled) and `░` (empty), 10 characters wide. -Percentages: 0%, 10%, 20%, ... 100% (in 10% increments). +Progress bars use: `+█+` (filled) and `+░+` (empty), 10 characters wide. +Percentages: 0%, 10%, 20%, … 100% (in 10% increments). diff --git a/panel-clades/clades/aerie/AERIE-ENSAID-DESIGN.adoc b/panel-clades/clades/aerie/AERIE-ENSAID-DESIGN.adoc new file mode 100644 index 00000000..b047ba22 --- /dev/null +++ b/panel-clades/clades/aerie/AERIE-ENSAID-DESIGN.adoc @@ -0,0 +1,328 @@ +== Aerie eNSAID Panel Suite — Design Document + +*Date*: 2026-03-08 *Author*: Jonathan D.A. Jewell + Claude Opus 4.6 +*Scope*: PanLL as an eNSAID for Aerie (CF-NDS) development *Status*: +Design (ready for implementation) + +=== What This Is + +A comprehensive panel suite that turns PanLL into an *embedded +Neurosymbolic AI Development environment* specifically for working on +Aerie — the Cyber-Focused Network Diagnostic Suite. This design covers +collaborative use (parent + child), embedded shell, recording/sharing, +and deep integration with the hyperpolymath ecosystem. + +=== Three-Panel Model Applied to Aerie + +==== Panel-L (Symbolic Constraints) + +* *Network path constraints*: "`Latency to target X must be < 50ms`" +* *BGP route validation rules*: "`Route to AS64512 must traverse no more +than 4 hops`" +* *Proof envelope requirements*: "`All responses MUST carry SHA-256 +proof`" +* *Policy gate constraints*: "`Module `+telemetry:read+` requires API +key`" +* *VCL-DT temporal constraints*: "`Audit events older than 30 days must +be in VeriSimDB`" +* *ABI/FFI type constraints*: From Idris2 dependent types +(TelemetrySample, RouteHop) + +==== Panel-N (Neural/Agentic Reasoning) + +* *Route anomaly detection*: AI analyses traceroute patterns, flags +suspicious hops +* *Latency pattern learning*: Learns baseline, detects ISP throttling +* *BGP hijack inference*: Compares expected vs actual AS paths +* *Proof validation reasoning*: Checks proof envelopes against +constraints +* *Code analysis*: ECHIDNA prover checks Aerie V-lang, Idris2, Zig code +* *OODA loop*: Observe network → Orient anomalies → Decide alerts → Act +(remediate) + +==== Panel-W (World/Results) + +* *Network topology heatmap*: Hop-by-hop RTT visualisation +* *Jitter smoke charts*: 24h SmokePing data rendered in panel +* *BGP forensics dashboard*: Route path visualisation with AS +annotations +* *Proof envelope inspector*: Expand/verify individual response proofs +* *VeriSimDB temporal audit*: Bitemporal query results with drift scores +* *Live telemetry feed*: Speed/latency/jitter from LibreSpeed + +''''' + +=== Panel Suite (13 Panels) + +==== 1. Valence Shell (MUST — Priority 1) + +*Kind*: loader | *Backend*: Tauri IPC | *Icon*: terminal + +The embedded shell for running Claude Code inside PanLL. Named after the +outermost electron shell — the interface where things bond. + +*Features*: - PTY-backed terminal emulator in a panel (xterm.js or +similar) - Claude Code invocation with +`+--dangerously-skip-permissions+` for trusted use - Session recording +(asciinema format) for replay/sharing - Screenshot capture of terminal +state (PNG via Tauri) - Split view: terminal + conversation history - +Collaborative mode: parent and child see same session - MCP connection +to BoJ server (so Claude has access to all cartridges) + +*Three-panel mapping*: - L: Shell environment constraints (PATH, env +vars, working directory) - N: Claude’s reasoning stream (monologue +display from Panel-N) - W: Command output, file previews, build results + +==== 2. Network Topology (MUST — Priority 2) + +*Kind*: network | *Backend*: HTTP (Aerie gateway) | *Icon*: network + +*Features*: - Live traceroute visualisation (hop-by-hop with RTT) - BGP +path overlay (AS numbers, peering points) - Latency heatmap +(colour-coded by RTT: green < yellow < red) - Multi-target comparison +(side-by-side routes) - Anomaly highlighting (from Panel-N analysis) - +Historical comparison (VeriSimDB temporal queries) + +==== 3. Probe Dashboard (MUST — Priority 3) + +*Kind*: viewer | *Backend*: HTTP (Aerie gateway) | *Icon*: gauge + +*Features*: - LibreSpeed telemetry (download/upload/jitter/latency) - +SmokePing smoke charts (24h jitter persistence) - Hyperglass BGP looking +glass results - Auto-refresh with configurable interval - Threshold +alerts (red/amber/green) - Export to proof envelope for forensic chain + +==== 4. Proof Inspector (MUST — Priority 4) + +*Kind*: viewer | *Backend*: HTTP | *Icon*: shield-check + +*Features*: - Expand any proof envelope (SHA-256 or Ed448) - Verify +proof against response payload - Chain-of-custody visualisation - Tamper +detection alerts - Proof statistics (pass/fail rate over time) + +==== 5. ABI/FFI Workbench (SHOULD — Priority 5) + +*Kind*: builder | *Backend*: Tauri | *Icon*: bridge + +*Features*: - Idris2 type browser (Types.idr, Layout.idr, Foreign.idr) - +Zig FFI implementation viewer (side-by-side with ABI) - Generated C +header inspector - Type mismatch detection (ABI vs FFI alignment) - +Build trigger (compile Zig FFI from panel) - ECHIDNA proof verification +of ABI types + +==== 6. API Explorer (SHOULD — Priority 6) + +*Kind*: viewer | *Backend*: HTTP | *Icon*: plug + +*Features*: - GraphQL schema browser + query builder - gRPC service +explorer + call tester - REST endpoint catalogue with try-it - +Triple-protocol comparison (same query, three formats) - Response diff +(compare GraphQL vs REST for same data) + +==== 7. Watcher (SHOULD — Priority 7) + +*Kind*: scanner | *Backend*: Tauri (filesystem) | *Icon*: eye + +*Features*: - File system watcher on Aerie source tree - Auto-rebuild on +V-lang file changes - Auto-recompile Zig FFI on changes - Test runner +(triggered by file saves) - Build status indicator (green/red/building) +- Diff preview (what changed since last build) + +==== 8. Container Orchestrator (SHOULD — Priority 8) + +*Kind*: builder | *Backend*: Tauri (podman CLI) | *Icon*: box + +*Features*: - Podman Compose status (6 services: gateway, librespeed, +smokeping, hyperglass, redis, verisim) - Start/stop/restart individual +services - Log viewer per container - Resource usage per container (CPU, +memory) - Health check status (green/red dots) - Port mapping display + +==== 9. Simulation/Emulation (COULD — Priority 9) + +*Kind*: viewer | *Backend*: HTTP | *Icon*: play-circle + +*Features*: - Network condition simulation (latency injection, packet +loss) - BGP route injection (test hijack detection) - Load testing +(concurrent probe requests) - SmokePing historical replay - "`What-if`" +scenario builder (modify network topology) + +==== 10. Capture & Share (COULD — Priority 10) + +*Kind*: loader | *Backend*: Tauri | *Icon*: camera + +*Features*: - Screenshot any panel or the full PanLL window - Record +panel interactions as GIF (via Tauri) - Export diagnostic reports as PDF +- Share session state (serialise model to JSON) - Collaborative +annotations (draw on screenshots) - Session replay (load saved model +state) + +==== 11. BoJ Cartridge Monitor (COULD — Priority 11) + +*Kind*: viewer | *Backend*: HTTP (BoJ adapter) | *Icon*: grid + +*Features*: - 2D capability matrix display (13 domains × 9 protocols) - +Active cartridge status (mounted/unmounted) - Guardian health dashboard +(severity, circuit breakers) - Resource usage per cartridge (from +boj_guardian) - Mount/unmount controls - Umoja federation peer status + +==== 12. panic-attack Scanner (COULD — Priority 12) + +*Kind*: scanner | *Backend*: Tauri CLI | *Icon*: zap + +Already partially implemented in PanLL. Enhanced for Aerie: - Run +`+assail+` against Aerie V-lang source - Run `+assault+` stress tests +against Aerie gateway - Event chain visualisation (from panic-attack +exports) - SARIF export for GitHub Security tab - Weak point categories +relevant to network code + +==== 13. VeriSimDB Explorer (CORRECTIVE — Priority 13) + +*Kind*: database | *Backend*: HTTP (port 8084) | *Icon*: database + +Already partially in PanLL Databases panel. Specialised for Aerie: - +VCL-DT query builder for audit events - Bitemporal query modes (as-of, +between, history) - Drift score monitoring - Entity explorer for Aerie +schema - Temporal audit trail visualisation + +''''' + +=== MuSt/Should/Could/Corrective/Adaptive/Perfective Analysis + +==== MUST (without these, the eNSAID is not usable) + +[arabic] +. *Valence Shell* — Core interaction point, Claude Code embedded +. *Network Topology* — Aerie’s primary visual output +. *Probe Dashboard* — Live data from Aerie’s probes +. *Proof Inspector* — Core Aerie differentiator (forensic proofs) + +==== SHOULD (significantly enhance the experience) + +[arabic, start=5] +. *ABI/FFI Workbench* — Development workflow for the three-layer stack +. *API Explorer* — Test the triple-mount API +. *Watcher* — Live feedback loop during development +. *Container Orchestrator* — Manage the 6-service stack + +==== COULD (nice-to-have, defer to later) + +[arabic, start=9] +. *Simulation/Emulation* — Advanced testing scenarios +. *Capture & Share* — Collaboration and documentation +. *BoJ Cartridge Monitor* — System health visibility +. *panic-attack Scanner* — Security scanning + +==== CORRECTIVE (fixes existing gaps) + +[arabic, start=13] +. *VeriSimDB Explorer* — Currently stub, needs real implementation + +==== ADAPTIVE (responds to changing context) + +* *Guardian integration* — The frozen-desktop incident shows the need +for resource monitoring in every panel that spawns processes +* *Collaborative mode* — Parent+child usage requires simplified views, +role-based access + +==== PERFECTIVE (optimisation and polish) + +* *Keyboard shortcuts* — Ctrl+1 through Ctrl+9 for panel switching +* *Panel presets* — "`Developer`" layout vs "`Operator`" layout vs +"`Collaborative`" layout +* *Accessibility* — Full ARIA, high contrast, screen reader support +(already started in PanLL) +* *Information humidity* — Vexometer-driven complexity reduction + +''''' + +=== Core Integration Points + +==== TypeLL + +* Type-check constraint expressions in Panel-L +* Validate Aerie’s V-lang types against ABI definitions +* Type-level routing rules for BGP constraints + +==== ECHIDNA + +* Prove Idris2 ABI properties (IsUnbreakable, Attested) +* Verify proof envelope correctness +* Trust level assessment for Aerie’s security claims + +==== NeSy (Neurosymbolic) + +* Route anomaly detection (neural pattern matching + symbolic BGP rules) +* Latency baseline learning + constraint violation detection +* Proof chain validation (symbolic) + response pattern analysis (neural) + +==== Agentic + +* OODA loop for network monitoring (Observe → Orient → Decide → Act) +* Autonomous probe scheduling based on anomaly detection +* Operator stress tracking via Vexometer + +==== BoJ Server + +* Mount `+observe-mcp+` cartridge for metrics integration +* Mount `+database-mcp+` for VeriSimDB access +* Mount `+nesy-mcp+` for neurosymbolic reasoning +* Mount `+proof-mcp+` for formal verification +* *Guardian module* monitors all spawned processes + +==== panic-attack + +* Scan Aerie gateway code for weak points +* Stress test probe endpoints +* Event chain import for forensic analysis + +==== proven-servers + +* BGP validation backends +* Cryptographic proof generation (Ed448) + +''''' + +=== Collaborative Mode (Parent + Child) + +==== Roles + +* *Operator* (parent): Full access, all panels, can modify constraints +* *Observer* (child): Read-only view, simplified panels, can ask Claude +questions + +==== Shared State + +* Both see the same Panel-W (results) +* Both see Claude’s reasoning in Panel-N +* Observer can highlight/annotate but not modify constraints + +==== Valence Shell Collaboration + +* Shared terminal session (both see commands and output) +* Turn-taking: Observer can type when Operator allows +* Claude responds to both, prefixing responses with who asked + +==== Safety + +* Observer cannot unmount cartridges or change network targets +* Dangerous operations require Operator confirmation +* Vexometer tracks both users’ cognitive load independently + +''''' + +=== Implementation Order + +[arabic] +. *Valence Shell* panel (ReScript + xterm.js + Tauri PTY) +. *Network Topology* panel (GraphQL client to Aerie gateway) +. *Probe Dashboard* panel (polling Aerie REST API) +. *Watcher* panel (Tauri filesystem events) +. *Proof Inspector* panel (response parsing + hash verification) +. Remaining panels in priority order + +Each panel follows the standard PanLL wiring process: 1. Clade +definition (.a2ml) 2. Model module (src/model/_Model.res) 3. Message +types (src/Msg.res addition) 4. Update handler (src/Update.res addition) +5. Component (src/components/_.res) 6. Command module +(src/commands/*Cmd.res) 7. Registry entry +(src/modules/PanelRegistry.res) 8. View wiring (src/View.res) diff --git a/panel-clades/clades/aerie/AERIE-ENSAID-DESIGN.md b/panel-clades/clades/aerie/AERIE-ENSAID-DESIGN.md deleted file mode 100644 index 0c6b2155..00000000 --- a/panel-clades/clades/aerie/AERIE-ENSAID-DESIGN.md +++ /dev/null @@ -1,305 +0,0 @@ -# Aerie eNSAID Panel Suite — Design Document - -**Date**: 2026-03-08 -**Author**: Jonathan D.A. Jewell + Claude Opus 4.6 -**Scope**: PanLL as an eNSAID for Aerie (CF-NDS) development -**Status**: Design (ready for implementation) - -## What This Is - -A comprehensive panel suite that turns PanLL into an **embedded Neurosymbolic AI Development environment** specifically for working on Aerie — the Cyber-Focused Network Diagnostic Suite. This design covers collaborative use (parent + child), embedded shell, recording/sharing, and deep integration with the hyperpolymath ecosystem. - -## Three-Panel Model Applied to Aerie - -### Panel-L (Symbolic Constraints) -- **Network path constraints**: "Latency to target X must be < 50ms" -- **BGP route validation rules**: "Route to AS64512 must traverse no more than 4 hops" -- **Proof envelope requirements**: "All responses MUST carry SHA-256 proof" -- **Policy gate constraints**: "Module `telemetry:read` requires API key" -- **VCL-DT temporal constraints**: "Audit events older than 30 days must be in VeriSimDB" -- **ABI/FFI type constraints**: From Idris2 dependent types (TelemetrySample, RouteHop) - -### Panel-N (Neural/Agentic Reasoning) -- **Route anomaly detection**: AI analyses traceroute patterns, flags suspicious hops -- **Latency pattern learning**: Learns baseline, detects ISP throttling -- **BGP hijack inference**: Compares expected vs actual AS paths -- **Proof validation reasoning**: Checks proof envelopes against constraints -- **Code analysis**: ECHIDNA prover checks Aerie V-lang, Idris2, Zig code -- **OODA loop**: Observe network → Orient anomalies → Decide alerts → Act (remediate) - -### Panel-W (World/Results) -- **Network topology heatmap**: Hop-by-hop RTT visualisation -- **Jitter smoke charts**: 24h SmokePing data rendered in panel -- **BGP forensics dashboard**: Route path visualisation with AS annotations -- **Proof envelope inspector**: Expand/verify individual response proofs -- **VeriSimDB temporal audit**: Bitemporal query results with drift scores -- **Live telemetry feed**: Speed/latency/jitter from LibreSpeed - ---- - -## Panel Suite (13 Panels) - -### 1. Valence Shell (MUST — Priority 1) -**Kind**: loader | **Backend**: Tauri IPC | **Icon**: terminal - -The embedded shell for running Claude Code inside PanLL. Named after the outermost electron shell — the interface where things bond. - -**Features**: -- PTY-backed terminal emulator in a panel (xterm.js or similar) -- Claude Code invocation with `--dangerously-skip-permissions` for trusted use -- Session recording (asciinema format) for replay/sharing -- Screenshot capture of terminal state (PNG via Tauri) -- Split view: terminal + conversation history -- Collaborative mode: parent and child see same session -- MCP connection to BoJ server (so Claude has access to all cartridges) - -**Three-panel mapping**: -- L: Shell environment constraints (PATH, env vars, working directory) -- N: Claude's reasoning stream (monologue display from Panel-N) -- W: Command output, file previews, build results - -### 2. Network Topology (MUST — Priority 2) -**Kind**: network | **Backend**: HTTP (Aerie gateway) | **Icon**: network - -**Features**: -- Live traceroute visualisation (hop-by-hop with RTT) -- BGP path overlay (AS numbers, peering points) -- Latency heatmap (colour-coded by RTT: green < yellow < red) -- Multi-target comparison (side-by-side routes) -- Anomaly highlighting (from Panel-N analysis) -- Historical comparison (VeriSimDB temporal queries) - -### 3. Probe Dashboard (MUST — Priority 3) -**Kind**: viewer | **Backend**: HTTP (Aerie gateway) | **Icon**: gauge - -**Features**: -- LibreSpeed telemetry (download/upload/jitter/latency) -- SmokePing smoke charts (24h jitter persistence) -- Hyperglass BGP looking glass results -- Auto-refresh with configurable interval -- Threshold alerts (red/amber/green) -- Export to proof envelope for forensic chain - -### 4. Proof Inspector (MUST — Priority 4) -**Kind**: viewer | **Backend**: HTTP | **Icon**: shield-check - -**Features**: -- Expand any proof envelope (SHA-256 or Ed448) -- Verify proof against response payload -- Chain-of-custody visualisation -- Tamper detection alerts -- Proof statistics (pass/fail rate over time) - -### 5. ABI/FFI Workbench (SHOULD — Priority 5) -**Kind**: builder | **Backend**: Tauri | **Icon**: bridge - -**Features**: -- Idris2 type browser (Types.idr, Layout.idr, Foreign.idr) -- Zig FFI implementation viewer (side-by-side with ABI) -- Generated C header inspector -- Type mismatch detection (ABI vs FFI alignment) -- Build trigger (compile Zig FFI from panel) -- ECHIDNA proof verification of ABI types - -### 6. API Explorer (SHOULD — Priority 6) -**Kind**: viewer | **Backend**: HTTP | **Icon**: plug - -**Features**: -- GraphQL schema browser + query builder -- gRPC service explorer + call tester -- REST endpoint catalogue with try-it -- Triple-protocol comparison (same query, three formats) -- Response diff (compare GraphQL vs REST for same data) - -### 7. Watcher (SHOULD — Priority 7) -**Kind**: scanner | **Backend**: Tauri (filesystem) | **Icon**: eye - -**Features**: -- File system watcher on Aerie source tree -- Auto-rebuild on V-lang file changes -- Auto-recompile Zig FFI on changes -- Test runner (triggered by file saves) -- Build status indicator (green/red/building) -- Diff preview (what changed since last build) - -### 8. Container Orchestrator (SHOULD — Priority 8) -**Kind**: builder | **Backend**: Tauri (podman CLI) | **Icon**: box - -**Features**: -- Podman Compose status (6 services: gateway, librespeed, smokeping, hyperglass, redis, verisim) -- Start/stop/restart individual services -- Log viewer per container -- Resource usage per container (CPU, memory) -- Health check status (green/red dots) -- Port mapping display - -### 9. Simulation/Emulation (COULD — Priority 9) -**Kind**: viewer | **Backend**: HTTP | **Icon**: play-circle - -**Features**: -- Network condition simulation (latency injection, packet loss) -- BGP route injection (test hijack detection) -- Load testing (concurrent probe requests) -- SmokePing historical replay -- "What-if" scenario builder (modify network topology) - -### 10. Capture & Share (COULD — Priority 10) -**Kind**: loader | **Backend**: Tauri | **Icon**: camera - -**Features**: -- Screenshot any panel or the full PanLL window -- Record panel interactions as GIF (via Tauri) -- Export diagnostic reports as PDF -- Share session state (serialise model to JSON) -- Collaborative annotations (draw on screenshots) -- Session replay (load saved model state) - -### 11. BoJ Cartridge Monitor (COULD — Priority 11) -**Kind**: viewer | **Backend**: HTTP (BoJ adapter) | **Icon**: grid - -**Features**: -- 2D capability matrix display (13 domains × 9 protocols) -- Active cartridge status (mounted/unmounted) -- Guardian health dashboard (severity, circuit breakers) -- Resource usage per cartridge (from boj_guardian) -- Mount/unmount controls -- Umoja federation peer status - -### 12. panic-attack Scanner (COULD — Priority 12) -**Kind**: scanner | **Backend**: Tauri CLI | **Icon**: zap - -Already partially implemented in PanLL. Enhanced for Aerie: -- Run `assail` against Aerie V-lang source -- Run `assault` stress tests against Aerie gateway -- Event chain visualisation (from panic-attack exports) -- SARIF export for GitHub Security tab -- Weak point categories relevant to network code - -### 13. VeriSimDB Explorer (CORRECTIVE — Priority 13) -**Kind**: database | **Backend**: HTTP (port 8084) | **Icon**: database - -Already partially in PanLL Databases panel. Specialised for Aerie: -- VCL-DT query builder for audit events -- Bitemporal query modes (as-of, between, history) -- Drift score monitoring -- Entity explorer for Aerie schema -- Temporal audit trail visualisation - ---- - -## MuSt/Should/Could/Corrective/Adaptive/Perfective Analysis - -### MUST (without these, the eNSAID is not usable) -1. **Valence Shell** — Core interaction point, Claude Code embedded -2. **Network Topology** — Aerie's primary visual output -3. **Probe Dashboard** — Live data from Aerie's probes -4. **Proof Inspector** — Core Aerie differentiator (forensic proofs) - -### SHOULD (significantly enhance the experience) -5. **ABI/FFI Workbench** — Development workflow for the three-layer stack -6. **API Explorer** — Test the triple-mount API -7. **Watcher** — Live feedback loop during development -8. **Container Orchestrator** — Manage the 6-service stack - -### COULD (nice-to-have, defer to later) -9. **Simulation/Emulation** — Advanced testing scenarios -10. **Capture & Share** — Collaboration and documentation -11. **BoJ Cartridge Monitor** — System health visibility -12. **panic-attack Scanner** — Security scanning - -### CORRECTIVE (fixes existing gaps) -13. **VeriSimDB Explorer** — Currently stub, needs real implementation - -### ADAPTIVE (responds to changing context) -- **Guardian integration** — The frozen-desktop incident shows the need for resource monitoring in every panel that spawns processes -- **Collaborative mode** — Parent+child usage requires simplified views, role-based access - -### PERFECTIVE (optimisation and polish) -- **Keyboard shortcuts** — Ctrl+1 through Ctrl+9 for panel switching -- **Panel presets** — "Developer" layout vs "Operator" layout vs "Collaborative" layout -- **Accessibility** — Full ARIA, high contrast, screen reader support (already started in PanLL) -- **Information humidity** — Vexometer-driven complexity reduction - ---- - -## Core Integration Points - -### TypeLL -- Type-check constraint expressions in Panel-L -- Validate Aerie's V-lang types against ABI definitions -- Type-level routing rules for BGP constraints - -### ECHIDNA -- Prove Idris2 ABI properties (IsUnbreakable, Attested) -- Verify proof envelope correctness -- Trust level assessment for Aerie's security claims - -### NeSy (Neurosymbolic) -- Route anomaly detection (neural pattern matching + symbolic BGP rules) -- Latency baseline learning + constraint violation detection -- Proof chain validation (symbolic) + response pattern analysis (neural) - -### Agentic -- OODA loop for network monitoring (Observe → Orient → Decide → Act) -- Autonomous probe scheduling based on anomaly detection -- Operator stress tracking via Vexometer - -### BoJ Server -- Mount `observe-mcp` cartridge for metrics integration -- Mount `database-mcp` for VeriSimDB access -- Mount `nesy-mcp` for neurosymbolic reasoning -- Mount `proof-mcp` for formal verification -- **Guardian module** monitors all spawned processes - -### panic-attack -- Scan Aerie gateway code for weak points -- Stress test probe endpoints -- Event chain import for forensic analysis - -### proven-servers -- BGP validation backends -- Cryptographic proof generation (Ed448) - ---- - -## Collaborative Mode (Parent + Child) - -### Roles -- **Operator** (parent): Full access, all panels, can modify constraints -- **Observer** (child): Read-only view, simplified panels, can ask Claude questions - -### Shared State -- Both see the same Panel-W (results) -- Both see Claude's reasoning in Panel-N -- Observer can highlight/annotate but not modify constraints - -### Valence Shell Collaboration -- Shared terminal session (both see commands and output) -- Turn-taking: Observer can type when Operator allows -- Claude responds to both, prefixing responses with who asked - -### Safety -- Observer cannot unmount cartridges or change network targets -- Dangerous operations require Operator confirmation -- Vexometer tracks both users' cognitive load independently - ---- - -## Implementation Order - -1. **Valence Shell** panel (ReScript + xterm.js + Tauri PTY) -2. **Network Topology** panel (GraphQL client to Aerie gateway) -3. **Probe Dashboard** panel (polling Aerie REST API) -4. **Watcher** panel (Tauri filesystem events) -5. **Proof Inspector** panel (response parsing + hash verification) -6. Remaining panels in priority order - -Each panel follows the standard PanLL wiring process: -1. Clade definition (.a2ml) -2. Model module (src/model/*Model.res) -3. Message types (src/Msg.res addition) -4. Update handler (src/Update.res addition) -5. Component (src/components/*.res) -6. Command module (src/commands/*Cmd.res) -7. Registry entry (src/modules/PanelRegistry.res) -8. View wiring (src/View.res) diff --git a/panel-clades/docs/AI-CONVENTIONS.adoc b/panel-clades/docs/AI-CONVENTIONS.adoc new file mode 100644 index 00000000..980985e2 --- /dev/null +++ b/panel-clades/docs/AI-CONVENTIONS.adoc @@ -0,0 +1,99 @@ +== AI Conventions (Authoritative Source) + +All AI coding agents working in this repository MUST follow these rules. +Per-tool config files (.cursorrules, .clinerules, etc.) reference this +document. + +=== Session Startup + +[arabic] +. Read `+0-AI-MANIFEST.a2ml+` FIRST (mandatory gatekeeper). +. Read `+.machine_readable/STATE.a2ml+` for current status and blockers. +. Read `+.machine_readable/anchors/ANCHOR.a2ml+` for canonical authority +boundaries. +. Read `+.machine_readable/policies/MAINTENANCE-AXES.a2ml+` for +maintenance/audit sequencing. +. Read `+.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml+` for +baseline controls. +. Read `+.machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml+` +for execution order. +. Read `+.machine_readable/AGENTIC.a2ml+` for agent constraints. + +=== License + +* All original code: *MPL-2.0* +* Fallback (platform-required only): MPL-2.0 with comment explaining +why. +* NEVER use AGPL-3.0. +* Preserve third-party licenses verbatim. +* Every source file needs `+# SPDX-License-Identifier: CC-BY-SA-4.0+`. + +=== Author Attribution + +* Name: *Jonathan D.A. Jewell* +* Email: *j.d.a.jewell@open.ac.uk* +* Copyright: +`+Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +` + +=== State Files + +State/metadata files, anchors, and policies (.a2ml) belong in +`+.machine_readable/+` ONLY. NEVER create STATE.a2ml, META.a2ml, +ECOSYSTEM.a2ml, AGENTIC.a2ml, NEUROSYM.a2ml, PLAYBOOK.a2ml, ANCHOR.a2ml, +MAINTENANCE-AXES.a2ml, MAINTENANCE-CHECKLIST.a2ml, or +SOFTWARE-DEVELOPMENT-APPROACH.a2ml in the repository root. + +=== Banned Patterns + +[width="100%",cols="14%,50%,36%",options="header",] +|=== +|Language |Banned |Reason +|Idris2 |`+believe_me+`, `+assert_total+` |Unsound escape hatches +|Haskell |`+unsafeCoerce+`, `+unsafePerformIO+` |Breaks type safety +|OCaml |`+Obj.magic+`, `+Obj.repr+`, `+Obj.obj+` |Unsafe casting +|Coq |`+Admitted+` |Unproven assumption +|Lean |`+sorry+` |Unproven assumption +|Rust |`+transmute+` (unless FFI + SAFETY:) |Unsound reinterpret +|=== + +=== Banned Languages + +[cols=",",options="header",] +|=== +|Banned |Use Instead +|TypeScript |ReScript +|Node.js / npm / bun |Deno +|Go |Rust +|Python |Julia / Rust +|=== + +=== Container Standard + +* Runtime: *Podman* (never Docker). +* File: *Containerfile* (never Dockerfile). +* Base images: `+cgr.dev/chainguard/wolfi-base:latest+` or +`+cgr.dev/chainguard/static:latest+`. + +=== ABI/FFI Standard + +* ABI definitions: *Idris2* with dependent types (`+src/abi/+`). +* FFI implementation: *Zig* with C ABI compatibility (`+ffi/zig/+`). +* Generated C headers: `+generated/abi/+`. + +=== Build System + +Use `+just+` (Justfile) for all build, test, lint, and format tasks. + +=== References + +* `+0-AI-MANIFEST.a2ml+` – universal AI entry point +* `+.machine_readable/AGENTIC.a2ml+` – agent permissions and constraints +* `+.machine_readable/STATE.a2ml+` – current project state +* `+.machine_readable/anchors/ANCHOR.a2ml+` – canonical authority and +policy boundary +* `+.machine_readable/policies/MAINTENANCE-AXES.a2ml+` – canonical axis +sequencing and audit requirements +* `+.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml+` – baseline +maintenance checklist policy +* `+.machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml+` – +axis execution approach policy diff --git a/panel-clades/docs/AI-CONVENTIONS.md b/panel-clades/docs/AI-CONVENTIONS.md deleted file mode 100644 index 197bfccc..00000000 --- a/panel-clades/docs/AI-CONVENTIONS.md +++ /dev/null @@ -1,84 +0,0 @@ - - - -# AI Conventions (Authoritative Source) - -All AI coding agents working in this repository MUST follow these rules. -Per-tool config files (.cursorrules, .clinerules, etc.) reference this document. - -## Session Startup - -1. Read `0-AI-MANIFEST.a2ml` FIRST (mandatory gatekeeper). -2. Read `.machine_readable/STATE.a2ml` for current status and blockers. -3. Read `.machine_readable/anchors/ANCHOR.a2ml` for canonical authority boundaries. -4. Read `.machine_readable/policies/MAINTENANCE-AXES.a2ml` for maintenance/audit sequencing. -5. Read `.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml` for baseline controls. -6. Read `.machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml` for execution order. -7. Read `.machine_readable/AGENTIC.a2ml` for agent constraints. - -## License - -- All original code: **MPL-2.0** -- Fallback (platform-required only): MPL-2.0 with comment explaining why. -- NEVER use AGPL-3.0. -- Preserve third-party licenses verbatim. -- Every source file needs `# SPDX-License-Identifier: CC-BY-SA-4.0`. - -## Author Attribution - -- Name: **Jonathan D.A. Jewell** -- Email: **j.d.a.jewell@open.ac.uk** -- Copyright: `Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) ` - -## State Files - -State/metadata files, anchors, and policies (.a2ml) belong in `.machine_readable/` ONLY. -NEVER create STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml, AGENTIC.a2ml, -NEUROSYM.a2ml, PLAYBOOK.a2ml, ANCHOR.a2ml, MAINTENANCE-AXES.a2ml, -MAINTENANCE-CHECKLIST.a2ml, or SOFTWARE-DEVELOPMENT-APPROACH.a2ml in the repository root. - -## Banned Patterns - -| Language | Banned | Reason | -|----------|-------------------------------------|---------------------------| -| Idris2 | `believe_me`, `assert_total` | Unsound escape hatches | -| Haskell | `unsafeCoerce`, `unsafePerformIO` | Breaks type safety | -| OCaml | `Obj.magic`, `Obj.repr`, `Obj.obj` | Unsafe casting | -| Coq | `Admitted` | Unproven assumption | -| Lean | `sorry` | Unproven assumption | -| Rust | `transmute` (unless FFI + SAFETY:) | Unsound reinterpret | - -## Banned Languages - -| Banned | Use Instead | -|---------------------|--------------------| -| TypeScript | ReScript | -| Node.js / npm / bun | Deno | -| Go | Rust | -| Python | Julia / Rust | - -## Container Standard - -- Runtime: **Podman** (never Docker). -- File: **Containerfile** (never Dockerfile). -- Base images: `cgr.dev/chainguard/wolfi-base:latest` or `cgr.dev/chainguard/static:latest`. - -## ABI/FFI Standard - -- ABI definitions: **Idris2** with dependent types (`src/abi/`). -- FFI implementation: **Zig** with C ABI compatibility (`ffi/zig/`). -- Generated C headers: `generated/abi/`. - -## Build System - -Use `just` (Justfile) for all build, test, lint, and format tasks. - -## References - -- `0-AI-MANIFEST.a2ml` -- universal AI entry point -- `.machine_readable/AGENTIC.a2ml` -- agent permissions and constraints -- `.machine_readable/STATE.a2ml` -- current project state -- `.machine_readable/anchors/ANCHOR.a2ml` -- canonical authority and policy boundary -- `.machine_readable/policies/MAINTENANCE-AXES.a2ml` -- canonical axis sequencing and audit requirements -- `.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml` -- baseline maintenance checklist policy -- `.machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml` -- axis execution approach policy diff --git a/panel-clades/docs/QUICKSTART.adoc b/panel-clades/docs/QUICKSTART.adoc new file mode 100644 index 00000000..1ea963fb --- /dev/null +++ b/panel-clades/docs/QUICKSTART.adoc @@ -0,0 +1,69 @@ +== Quickstart + +Get up and running in 60 seconds. + +=== Prerequisites + +* https://git-scm.com/[Git] 2.40+ +* https://github.com/casey/just[just] (command runner) +* Your language toolchain (see `+Justfile+` for details) + +=== From Template (New Project) + +[source,bash] +---- +git clone https://github.com/hyperpolymath/rsr-template-repo my-project +cd my-project +rm -rf .git && git init -b main +just init # interactive placeholder replacement +---- + +=== Clone and Setup (Existing Project) + +[source,bash] +---- +git clone https://github.com/hyperpolymath/panll.git +cd panll +just deps +---- + +=== Build and Test + +[source,bash] +---- +just build +just test +---- + +=== Verify Everything Works + +[source,bash] +---- +just check +---- + +=== Project Structure + +.... +src/ # Source code +tests/ # Test suite +benches/ # Benchmarks +docs/ # Documentation +.github/ # CI/CD workflows +.... + +=== What Next? + +* Browse the link:.[docs/] for architecture and conventions +* Run `+just --list+` to see all available commands +* Read link:../CONTRIBUTING.md[CONTRIBUTING.md] when you are ready to +contribute + +=== Troubleshooting + +If `+just deps+` fails, ensure your toolchain version matches the +project requirements listed in the `+Justfile+` or +`+.machine_readable/ECOSYSTEM.a2ml+`. + +Open a https://github.com/hyperpolymath/panll/discussions[Discussion] if +you get stuck. diff --git a/panel-clades/docs/QUICKSTART.md b/panel-clades/docs/QUICKSTART.md deleted file mode 100644 index 4f3362da..00000000 --- a/panel-clades/docs/QUICKSTART.md +++ /dev/null @@ -1,64 +0,0 @@ - -# Quickstart - -Get up and running in 60 seconds. - -## Prerequisites - -- [Git](https://git-scm.com/) 2.40+ -- [just](https://github.com/casey/just) (command runner) -- Your language toolchain (see `Justfile` for details) - -## From Template (New Project) - -```bash -git clone https://github.com/hyperpolymath/rsr-template-repo my-project -cd my-project -rm -rf .git && git init -b main -just init # interactive placeholder replacement -``` - -## Clone and Setup (Existing Project) - -```bash -git clone https://github.com/hyperpolymath/panll.git -cd panll -just deps -``` - -## Build and Test - -```bash -just build -just test -``` - -## Verify Everything Works - -```bash -just check -``` - -## Project Structure - -``` -src/ # Source code -tests/ # Test suite -benches/ # Benchmarks -docs/ # Documentation -.github/ # CI/CD workflows -``` - -## What Next? - -- Browse the [docs/](.) for architecture and conventions -- Run `just --list` to see all available commands -- Read [CONTRIBUTING.md](../CONTRIBUTING.md) when you are ready to contribute - -## Troubleshooting - -If `just deps` fails, ensure your toolchain version matches the -project requirements listed in the `Justfile` or `.machine_readable/ECOSYSTEM.a2ml`. - -Open a [Discussion](https://github.com/hyperpolymath/panll/discussions) -if you get stuck. diff --git a/panel-clades/docs/THREAT-MODEL.adoc b/panel-clades/docs/THREAT-MODEL.adoc new file mode 100644 index 00000000..66be7299 --- /dev/null +++ b/panel-clades/docs/THREAT-MODEL.adoc @@ -0,0 +1,254 @@ +== Threat Model: Panll + +=== Document Info + +[cols=",",options="header",] +|=== +|Field |Value +|Project |Panll +|Version |1.0 +|Last Reviewed |2026-03-16 +|Author |Jonathan D.A. Jewell +|Methodology |STRIDE +|=== + +=== Scope + +==== In Scope + +* Application source code and build pipeline +* CI/CD workflows (GitHub Actions) +* Container images and runtime environment +* Secrets and credential management +* Dependencies (direct and transitive) +* Deployment artifacts (binaries, containers, SBOM) + +==== Out of Scope + +* Physical security of hosting infrastructure +* GitHub/GitLab platform-level vulnerabilities +* End-user device security +* Social engineering attacks against maintainers (handled by org policy) + +=== System Overview + +Brief description of Panll and its architecture. + +____ +See link:../TOPOLOGY.md[TOPOLOGY.md] for the full architecture diagram +and completion dashboard. +____ + +=== Assets + +[width="100%",cols="25%,16%,13%,46%",options="header",] +|=== +|Asset |Classification |Owner |Notes +|Source code |Internal |Maintainers |Public repos are still +internal-integrity + +|Signing keys |Restricted |Release lead |Signing keys (e.g., Ed25519), +GPG keys + +|CI/CD secrets |Restricted |Maintainers |GITHUB_TOKEN, deploy tokens, +PATs + +|User/contributor data |Confidential |Org |Emails, contributor identity + +|Build artifacts |Internal |CI pipeline |Binaries, WASM bundles + +|Container images |Internal |CI pipeline |Chainguard-based, signed via +image signing tool + +|SBOM / provenance |Public |CI pipeline |SLSA attestations + +|Dependencies |Public |Lockfile |Cargo.lock, deno.lock, gleam.toml + +|Infrastructure config |Confidential |Maintainers |Containerfiles, +compose files, orchestration config +|=== + +=== Trust Boundaries + +[width="100%",cols="35%,32%,33%",options="header",] +|=== +|Boundary |From (Lower Trust) |To (Higher Trust) +|Pull request submission |External contributor |Repository codebase + +|CI/CD workflow execution |Workflow definition |Runner with secrets +access + +|Container build boundary |Build stage |Runtime stage + +|External API calls |Third-party service |Application internals + +|User input (CLI/Web) |End user |Application logic + +|Dependency resolution |Package registry |Build environment + +|Forge mirroring |GitHub |GitLab / Bitbucket +|=== + +=== Threat Actors + +[width="100%",cols="39%,44%,17%",options="header",] +|=== +|Actor |Motivation |Capability +|Script kiddie |Vandalism, clout |Low +|Disgruntled contributor |Sabotage, backdoor insertion |Medium +|Supply chain attacker |Wide-impact compromise |High +|Nation state |Espionage, disruption |Very High +|Automated bot |Credential stuffing, spam PRs |Low-Medium +|=== + +=== STRIDE Analysis + +==== Spoofing + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Unsigned commits impersonate maintainer |Source code |Medium |High +|High |Require GPG-signed commits; vigilant code review + +|Forged bot actions (automated agents) |CI/CD pipeline |Low |High +|Medium |Bot tokens scoped minimally; audit bot activity + +|Spoofed package registry identity |Dependencies |Low |High |Medium |Pin +dependencies by hash; verify provenance +|=== + +==== Tampering + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Malicious pull request |Source code |Medium |High |High |Branch +protection; required reviews; CodeQL + +|Dependency poisoning (typosquat) |Dependencies |Medium |High |High +|Lockfiles; secret-scanner; security scans + +|Tampered container base image |Container images |Low |High |Medium +|Chainguard images; image signing verification + +|Workflow file modification |CI/CD pipeline |Low |High |Medium +|CODEOWNERS on .github/; workflow-linter +|=== + +==== Repudiation + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Unlogged deployment |Build artifacts |Medium |Medium |Medium |SLSA +provenance; deployment audit trail + +|Denied merge of vulnerable code |Source code |Low |Medium |Low |Git +history is immutable; signed commits + +|Secret rotation without record |CI/CD secrets |Low |Low |Low |Secret +rotation logged in STATE.a2ml +|=== + +==== Information Disclosure + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Secrets leaked in git history |CI/CD secrets |Medium |High |High +|TruffleHog in CI; secret-scanner workflow + +|Verbose error messages in prod |Application logic |Medium |Medium +|Medium |Sanitize outputs; structured logging + +|SBOM reveals internal structure |Infrastructure |Low |Low |Low +|Accepted risk; SBOM is intentionally public +|=== + +==== Denial of Service + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|CI resource exhaustion (fork bomb in PR) |CI/CD pipeline |Medium +|Medium |Medium |Concurrency limits; timeout on workflows + +|Spam issues/PRs flooding triage |Maintainer time |Medium |Low |Low +|GitHub rate limits; bot auto-close stale + +|Large binary commits bloating repo |Source code |Low |Medium |Low +|.gitattributes LFS policy; pre-commit hooks +|=== + +==== Elevation of Privilege + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Workflow injection via PR title/body |CI/CD pipeline |Medium |High +|High |Never interpolate PR fields in `+run:+`; use env vars + +|GITHUB_TOKEN over-scoped |CI/CD secrets |Medium |High |High +|`+permissions: read-all+` default; per-job scoping + +|Container escape |Runtime environment |Low |High |Medium |Hardened +container runtime; read-only rootfs; no-new-privileges + +|Compromised action dependency |CI/CD pipeline |Medium |High |High +|SHA-pin all actions; never use `+@latest+` tags +|=== + +=== Mitigations in Place + +* *SLSA Provenance*: Build attestations via slsa-github-generator +* *Secret Scanning*: TruffleHog + secret-scanner workflow on every push +* *Static Analysis*: CodeQL on supported languages +* *Supply Chain*: OpenSSF Scorecard (scorecard.yml + +scorecard-enforcer.yml) +* *Container Signing*: Ed25519 signatures on all published images +(optional: use your signing tool) +* *Container Runtime*: Hardened container runtime with formal +verification (optional) +* *Dependency Pinning*: All GitHub Actions SHA-pinned; lockfiles +committed +* *Workflow Validation*: workflow-linter.yml checks all workflow changes +* *Security Scanning*: Neurosymbolic scanning (hypatia-scan.yml, +optional) +* *Bot Governance*: Bot orchestration with confidence thresholds +(optional) +* *Edge Security*: Gateway with policy enforcement (optional, where +applicable) +* *SBOM*: Generated and published with releases + +=== Residual Risks + +[width="100%",cols="39%,41%,20%",options="header",] +|=== +|Risk |Accepted Because |Review Trigger +|Zero-day in GitHub Actions runner |Platform responsibility; no feasible +mitigation |GitHub advisory + +|Maintainer account compromise |Mitigated by 2FA requirement; residual +remains |Any suspicious activity + +|Transitive dependency vulnerability (0-day) |Lockfiles limit blast +radius; scanning catches known CVEs |CVE database update + +|SBOM exposes internal component names |Transparency is a design goal +|Policy change +|=== + +=== Review Schedule + +This threat model should be reviewed: + +* *Quarterly* as a standing item +* *When architecture changes* (new services, new trust boundaries, new +deployment targets) +* *Before major releases* (v1.0, v2.0, etc.) +* *After any security incident* affecting this project or its +dependencies + +Reviewer should update the "`Last Reviewed`" date and version in +Document Info above. diff --git a/panel-clades/docs/THREAT-MODEL.md b/panel-clades/docs/THREAT-MODEL.md deleted file mode 100644 index c51bdd1b..00000000 --- a/panel-clades/docs/THREAT-MODEL.md +++ /dev/null @@ -1,161 +0,0 @@ - - - -# Threat Model: Panll - -## Document Info - -| Field | Value | -|---------------|--------------------------------| -| Project | Panll | -| Version | 1.0 | -| Last Reviewed | 2026-03-16 | -| Author | Jonathan D.A. Jewell | -| Methodology | STRIDE | - -## Scope - -### In Scope - -- Application source code and build pipeline -- CI/CD workflows (GitHub Actions) -- Container images and runtime environment -- Secrets and credential management -- Dependencies (direct and transitive) -- Deployment artifacts (binaries, containers, SBOM) - -### Out of Scope - -- Physical security of hosting infrastructure -- GitHub/GitLab platform-level vulnerabilities -- End-user device security -- Social engineering attacks against maintainers (handled by org policy) - -## System Overview - -Brief description of Panll and its architecture. - -> See [TOPOLOGY.md](../TOPOLOGY.md) for the full architecture diagram and completion dashboard. - -## Assets - -| Asset | Classification | Owner | Notes | -|----------------------|----------------|-------------|--------------------------------------------| -| Source code | Internal | Maintainers | Public repos are still internal-integrity | -| Signing keys | Restricted | Release lead | Signing keys (e.g., Ed25519), GPG keys | -| CI/CD secrets | Restricted | Maintainers | GITHUB_TOKEN, deploy tokens, PATs | -| User/contributor data | Confidential | Org | Emails, contributor identity | -| Build artifacts | Internal | CI pipeline | Binaries, WASM bundles | -| Container images | Internal | CI pipeline | Chainguard-based, signed via image signing tool | -| SBOM / provenance | Public | CI pipeline | SLSA attestations | -| Dependencies | Public | Lockfile | Cargo.lock, deno.lock, gleam.toml | -| Infrastructure config | Confidential | Maintainers | Containerfiles, compose files, orchestration config | - -## Trust Boundaries - -| Boundary | From (Lower Trust) | To (Higher Trust) | -|-----------------------------|---------------------------|----------------------------| -| Pull request submission | External contributor | Repository codebase | -| CI/CD workflow execution | Workflow definition | Runner with secrets access | -| Container build boundary | Build stage | Runtime stage | -| External API calls | Third-party service | Application internals | -| User input (CLI/Web) | End user | Application logic | -| Dependency resolution | Package registry | Build environment | -| Forge mirroring | GitHub | GitLab / Bitbucket | - -## Threat Actors - -| Actor | Motivation | Capability | -|--------------------------|-------------------------------|------------| -| Script kiddie | Vandalism, clout | Low | -| Disgruntled contributor | Sabotage, backdoor insertion | Medium | -| Supply chain attacker | Wide-impact compromise | High | -| Nation state | Espionage, disruption | Very High | -| Automated bot | Credential stuffing, spam PRs | Low-Medium | - -## STRIDE Analysis - -### Spoofing - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Unsigned commits impersonate maintainer | Source code | Medium | High | High | Require GPG-signed commits; vigilant code review | -| Forged bot actions (automated agents) | CI/CD pipeline | Low | High | Medium | Bot tokens scoped minimally; audit bot activity | -| Spoofed package registry identity | Dependencies | Low | High | Medium | Pin dependencies by hash; verify provenance | - -### Tampering - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Malicious pull request | Source code | Medium | High | High | Branch protection; required reviews; CodeQL | -| Dependency poisoning (typosquat) | Dependencies | Medium | High | High | Lockfiles; secret-scanner; security scans | -| Tampered container base image | Container images | Low | High | Medium | Chainguard images; image signing verification | -| Workflow file modification | CI/CD pipeline | Low | High | Medium | CODEOWNERS on .github/; workflow-linter | - -### Repudiation - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Unlogged deployment | Build artifacts | Medium | Medium | Medium | SLSA provenance; deployment audit trail | -| Denied merge of vulnerable code | Source code | Low | Medium | Low | Git history is immutable; signed commits | -| Secret rotation without record | CI/CD secrets | Low | Low | Low | Secret rotation logged in STATE.a2ml | - -### Information Disclosure - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Secrets leaked in git history | CI/CD secrets | Medium | High | High | TruffleHog in CI; secret-scanner workflow | -| Verbose error messages in prod | Application logic | Medium | Medium | Medium | Sanitize outputs; structured logging | -| SBOM reveals internal structure | Infrastructure | Low | Low | Low | Accepted risk; SBOM is intentionally public | - -### Denial of Service - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| CI resource exhaustion (fork bomb in PR) | CI/CD pipeline | Medium | Medium | Medium | Concurrency limits; timeout on workflows | -| Spam issues/PRs flooding triage | Maintainer time | Medium | Low | Low | GitHub rate limits; bot auto-close stale | -| Large binary commits bloating repo | Source code | Low | Medium | Low | .gitattributes LFS policy; pre-commit hooks | - -### Elevation of Privilege - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Workflow injection via PR title/body | CI/CD pipeline | Medium | High | High | Never interpolate PR fields in `run:`; use env vars | -| GITHUB_TOKEN over-scoped | CI/CD secrets | Medium | High | High | `permissions: read-all` default; per-job scoping | -| Container escape | Runtime environment | Low | High | Medium | Hardened container runtime; read-only rootfs; no-new-privileges | -| Compromised action dependency | CI/CD pipeline | Medium | High | High | SHA-pin all actions; never use `@latest` tags | - -## Mitigations in Place - -- **SLSA Provenance**: Build attestations via slsa-github-generator -- **Secret Scanning**: TruffleHog + secret-scanner workflow on every push -- **Static Analysis**: CodeQL on supported languages -- **Supply Chain**: OpenSSF Scorecard (scorecard.yml + scorecard-enforcer.yml) -- **Container Signing**: Ed25519 signatures on all published images (optional: use your signing tool) -- **Container Runtime**: Hardened container runtime with formal verification (optional) -- **Dependency Pinning**: All GitHub Actions SHA-pinned; lockfiles committed -- **Workflow Validation**: workflow-linter.yml checks all workflow changes -- **Security Scanning**: Neurosymbolic scanning (hypatia-scan.yml, optional) -- **Bot Governance**: Bot orchestration with confidence thresholds (optional) -- **Edge Security**: Gateway with policy enforcement (optional, where applicable) -- **SBOM**: Generated and published with releases - -## Residual Risks - -| Risk | Accepted Because | Review Trigger | -|-----------------------------------------------|---------------------------------------------------|-------------------------| -| Zero-day in GitHub Actions runner | Platform responsibility; no feasible mitigation | GitHub advisory | -| Maintainer account compromise | Mitigated by 2FA requirement; residual remains | Any suspicious activity | -| Transitive dependency vulnerability (0-day) | Lockfiles limit blast radius; scanning catches known CVEs | CVE database update | -| SBOM exposes internal component names | Transparency is a design goal | Policy change | - -## Review Schedule - -This threat model should be reviewed: - -- **Quarterly** as a standing item -- **When architecture changes** (new services, new trust boundaries, new deployment targets) -- **Before major releases** (v1.0, v2.0, etc.) -- **After any security incident** affecting this project or its dependencies - -Reviewer should update the "Last Reviewed" date and version in Document Info above. diff --git a/panel-clades/docs/decisions/0000-template.adoc b/panel-clades/docs/decisions/0000-template.adoc new file mode 100644 index 00000000..de603adf --- /dev/null +++ b/panel-clades/docs/decisions/0000-template.adoc @@ -0,0 +1,33 @@ +== [NUMBER]. [TITLE] + +Date: YYYY-MM-DD + +=== Status + +{empty}[Proposed | Accepted | Deprecated | Superseded by +link:NNNN-title.md[ADR-NNNN] | Rejected] + +=== Context + +What is the issue that we’re seeing that is motivating this decision or +change? + +=== Decision + +What is the change that we’re proposing and/or doing? + +=== Consequences + +What becomes easier or more difficult to do because of this change? + +==== Positive + +* … + +==== Negative + +* … + +==== Neutral + +* … diff --git a/panel-clades/docs/decisions/0000-template.md b/panel-clades/docs/decisions/0000-template.md deleted file mode 100644 index b20356ff..00000000 --- a/panel-clades/docs/decisions/0000-template.md +++ /dev/null @@ -1,34 +0,0 @@ - - - -# [NUMBER]. [TITLE] - -Date: YYYY-MM-DD - -## Status - -[Proposed | Accepted | Deprecated | Superseded by [ADR-NNNN](NNNN-title.md) | Rejected] - -## Context - -What is the issue that we're seeing that is motivating this decision or change? - -## Decision - -What is the change that we're proposing and/or doing? - -## Consequences - -What becomes easier or more difficult to do because of this change? - -### Positive - -- ... - -### Negative - -- ... - -### Neutral - -- ... diff --git a/panel-clades/docs/decisions/0001-adopt-rsr-standard.adoc b/panel-clades/docs/decisions/0001-adopt-rsr-standard.adoc new file mode 100644 index 00000000..0dbd05a3 --- /dev/null +++ b/panel-clades/docs/decisions/0001-adopt-rsr-standard.adoc @@ -0,0 +1,94 @@ +== 1. Adopt Rhodium Standard Repository (RSR) Template + +Date: 2026-02-14 + +=== Status + +Accepted + +=== Context + +Managing multiple repositories with an ad-hoc approach led to +significant inconsistencies across the ecosystem. Common problems +included: + +* Missing or incomplete configuration files (SECURITY.md, +CONTRIBUTING.md, .editorconfig, etc.) +* State files (STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml) placed in the +repository root instead of the canonical `+.machine_readable/+` +directory +* Duplicate or conflicting workflow definitions across repos +* No standardized entry point for AI agents interacting with +repositories +* Inconsistent bot directive configurations leading to unreliable +automation +* No contractile enforcement or Justfile automation + +Without a single source of truth for repository structure, each new repo +required manual setup and inevitably drifted from best practices over +time. + +=== Decision + +Adopt the Rhodium Standard Repository (RSR) template +(`+rsr-template-repo+`) as the canonical starting point for all new +repositories. Existing repositories will migrate incrementally as they +receive active development. + +The RSR template provides: + +* *Machine-readable state files* in `+.machine_readable/+` (STATE.a2ml, +ECOSYSTEM.a2ml, META.a2ml, AGENTIC.a2ml, NEUROSYM.a2ml, PLAYBOOK.a2ml) +* *AI manifest* (`+0-AI-MANIFEST.a2ml+`) as a universal entry point for +all AI agents +* *Bot directives* in `+.machine_readable/bot_directives/+` for bot +orchestration integration +* *Contractiles* in `+.machine_readable/contractiles/+` (k9, dust, lust, +must, trust) for policy enforcement +* *Standardized workflows* (16+ GitHub Actions workflows, all +SHA-pinned) +* *Justfile automation* with standard recipes for common tasks +* *Security and governance files*: SECURITY.md, CONTRIBUTING.md, +CODE_OF_CONDUCT.md, LICENSE (MPL-2.0) +* *Architecture Decision Records* in `+docs/decisions/+` + +New repositories are created by cloning the template: + +[source,bash] +---- +git clone https://github.com/hyperpolymath/rsr-template-repo new-repo-name +cd new-repo-name +rm -rf .git && git init +---- + +=== Consequences + +==== Positive + +* Consistency across all repositories, enforced from creation +* Automated compliance checking via `+rsr-antipattern.yml+` workflow +* Bot fleet can operate reliably across all repos with predictable +structure +* AI agents (Claude, Gemini, etc.) have a standardized entry point via +`+0-AI-MANIFEST.a2ml+` +* New contributors can onboard faster with familiar, documented +structure +* Reduced maintenance burden: fix once in template, propagate to all +repos +* Machine-readable state enables tooling and automation pipelines + +==== Negative + +* Migration effort for existing repos requires time and attention +* Learning curve for contributors unfamiliar with RSR conventions +* Template updates need propagation mechanism to existing repos +* Some repos may have unique needs that do not fit the standard template +without customization + +==== Neutral + +* Existing CI/CD pipelines continue to work; RSR workflows are additive +* Third-party dependencies retain their original licenses regardless of +repo structure +* ADR process itself is part of the template, enabling future decisions +to be recorded consistently diff --git a/panel-clades/docs/decisions/0001-adopt-rsr-standard.md b/panel-clades/docs/decisions/0001-adopt-rsr-standard.md deleted file mode 100644 index bcb69335..00000000 --- a/panel-clades/docs/decisions/0001-adopt-rsr-standard.md +++ /dev/null @@ -1,85 +0,0 @@ - - - -# 1. Adopt Rhodium Standard Repository (RSR) Template - -Date: 2026-02-14 - -## Status - -Accepted - -## Context - -Managing multiple repositories with an ad-hoc approach led to significant -inconsistencies across the ecosystem. Common problems included: - -- Missing or incomplete configuration files (SECURITY.md, CONTRIBUTING.md, - .editorconfig, etc.) -- State files (STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml) placed in the repository - root instead of the canonical `.machine_readable/` directory -- Duplicate or conflicting workflow definitions across repos -- No standardized entry point for AI agents interacting with repositories -- Inconsistent bot directive configurations leading to unreliable automation -- No contractile enforcement or Justfile automation - -Without a single source of truth for repository structure, each new repo -required manual setup and inevitably drifted from best practices over time. - -## Decision - -Adopt the Rhodium Standard Repository (RSR) template (`rsr-template-repo`) as -the canonical starting point for all new repositories. Existing repositories -will migrate incrementally as they receive active development. - -The RSR template provides: - -- **Machine-readable state files** in `.machine_readable/` (STATE.a2ml, - ECOSYSTEM.a2ml, META.a2ml, AGENTIC.a2ml, NEUROSYM.a2ml, PLAYBOOK.a2ml) -- **AI manifest** (`0-AI-MANIFEST.a2ml`) as a universal entry point for all - AI agents -- **Bot directives** in `.machine_readable/bot_directives/` for bot orchestration integration -- **Contractiles** in `.machine_readable/contractiles/` (k9, dust, lust, must, trust) for - policy enforcement -- **Standardized workflows** (16+ GitHub Actions workflows, all SHA-pinned) -- **Justfile automation** with standard recipes for common tasks -- **Security and governance files**: SECURITY.md, CONTRIBUTING.md, - CODE_OF_CONDUCT.md, LICENSE (MPL-2.0) -- **Architecture Decision Records** in `docs/decisions/` - -New repositories are created by cloning the template: - -```bash -git clone https://github.com/hyperpolymath/rsr-template-repo new-repo-name -cd new-repo-name -rm -rf .git && git init -``` - -## Consequences - -### Positive - -- Consistency across all repositories, enforced from creation -- Automated compliance checking via `rsr-antipattern.yml` workflow -- Bot fleet can operate reliably across all repos with predictable structure -- AI agents (Claude, Gemini, etc.) have a standardized entry point via - `0-AI-MANIFEST.a2ml` -- New contributors can onboard faster with familiar, documented structure -- Reduced maintenance burden: fix once in template, propagate to all repos -- Machine-readable state enables tooling and automation pipelines - -### Negative - -- Migration effort for existing repos requires time and attention -- Learning curve for contributors unfamiliar with RSR conventions -- Template updates need propagation mechanism to existing repos -- Some repos may have unique needs that do not fit the standard template - without customization - -### Neutral - -- Existing CI/CD pipelines continue to work; RSR workflows are additive -- Third-party dependencies retain their original licenses regardless of - repo structure -- ADR process itself is part of the template, enabling future decisions - to be recorded consistently diff --git a/panel-clades/docs/decisions/README.adoc b/panel-clades/docs/decisions/README.adoc new file mode 100644 index 00000000..3dc7a485 --- /dev/null +++ b/panel-clades/docs/decisions/README.adoc @@ -0,0 +1,18 @@ +== Architecture Decision Records + +We record significant architectural decisions using +https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions[Architecture +Decision Records (ADRs)], as described by Michael Nygard. + +Each ADR captures the context, decision, and consequences of a choice +that affects the project’s structure, dependencies, or conventions. + +=== Creating a new ADR + +[source,bash] +---- +just adr "Title of decision" +---- + +This creates a new numbered file in `+docs/decisions/+` from the +template at `+0000-template.md+`. diff --git a/panel-clades/docs/decisions/README.md b/panel-clades/docs/decisions/README.md deleted file mode 100644 index 1ee15bbf..00000000 --- a/panel-clades/docs/decisions/README.md +++ /dev/null @@ -1,16 +0,0 @@ - - - -# Architecture Decision Records - -We record significant architectural decisions using [Architecture Decision Records (ADRs)](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions), as described by Michael Nygard. - -Each ADR captures the context, decision, and consequences of a choice that affects the project's structure, dependencies, or conventions. - -## Creating a new ADR - -```bash -just adr "Title of decision" -``` - -This creates a new numbered file in `docs/decisions/` from the template at `0000-template.md`. diff --git a/panel-clades/docs/maintenance/MAINTENANCE-CHECKLIST.adoc b/panel-clades/docs/maintenance/MAINTENANCE-CHECKLIST.adoc new file mode 100644 index 00000000..0e66c0ef --- /dev/null +++ b/panel-clades/docs/maintenance/MAINTENANCE-CHECKLIST.adoc @@ -0,0 +1,670 @@ +== Maintenance Checklist (Cross-Repo) + +Use this as a repeatable maintenance runbook for any repo. + +Companion policy: + +* `+docs/practice/SOFTWARE-DEVELOPMENT-APPROACH.adoc+` (human-readable) +* `+.machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml+` +(machine-readable) + +=== Canonical Repo Baseline (Final) + +Apply this baseline to every repo unless an explicit exception is +recorded. + +==== Three-Axis Default Model + +* [ ] Axis 1 (scope priority, runs first): `+must > intend > like+` +* [ ] Axis 2 (maintenance priority): +`+corrective > adaptive > perfective+` +* [ ] Axis 3 (audit priority): `+systems > compliance > effects+` +* [ ] Perfective items are derived from Axis 1 honest state (not started +independently). + +==== Axis 1 Scoping Pass (Mandatory) + +Before Axis 2/3 execution, assemble a scoped worklist from evidence: + +* [ ] Read and reconcile: `+README+`, roadmap, status docs, maintenance +checklist, and current CI/security docs. +* [ ] Scan for unfinished markers: `+TODO+`, `+FIXME+`, `+XXX+`, +`+HACK+`, `+STUB+`, `+PARTIAL+`. +* [ ] If Idris is present, scan unsoundness markers: `+believe_me+`, +`+assert_total+`. +* [ ] Identify declared intent vs actual implementation (docs honesty +check). +* [ ] Produce a scope assembly artifact with prioritized entries under: +** `+must+` (release blockers / safety / correctness) +** `+intend+` (planned near-term) +** `+like+` (nice-to-have) + +==== Axis 2 Maintenance Execution Rules + +* [ ] Corrective first: fix breakage, defects, regressions, safety +issues. +* [ ] Adaptive second: reconcile changed scope, remove stale references, +cull no-longer-relevant work. +* [ ] Perfective third: only from current honest state established by +Axis 1 and updated by corrective/adaptive actions. + +==== Axis 3 Audit Rules + +* [ ] Verify systems are in place and actually operating. +* [ ] Verify documentation explains the real/current state (not +aspirational-only), including documented exceptions. +* [ ] Verify safety and security controls are present, active, and +evidenced. +* [ ] Verify observed effects/impacts are captured and reviewed. +* [ ] Effects audit includes: +** benchmark execution and recorded results (with before/after where +relevant) +** explicit maintainer dialogue/status review on what changed, why, and +next risks +* [ ] Audit compliance seams/compromises explicitly: +** policy exceptions are recorded with rationale, scope, and +expiry/review +** exception does not silently broaden into general policy drift +** language-policy contamination checks run (example: a single TS +exception must not trigger broad TypeScript conversion) +** run `+panic-attack+` as the compliance-audit scanner +** run ecological checking under effects (using sustainabot guidance as +current baseline) + +==== Generic Cleanup And Finish-Off Pass + +Run this pass at the end of a corrective/adaptive/perfective cycle: + +* [ ] Root cleanup: +** keep only required control/entry files in root +** move non-essential docs/reports/fixtures to canonical folders +* [ ] Remove or archive stale work: +** close out completed TODO/STUB/PARTIAL items +** cull obsolete references, dead files, and superseded plans +* [ ] Documentation finish-off: +** ensure README, roadmap, status, and wiki match actual implementation +state +** ensure machine-readable policy/state files match human docs +* [ ] Security/compliance finish-off: +** run compliance scanner (`+panic-attack+`) and resolve high-priority +findings +** verify exception register and seams/compromises are explicitly +bounded +* [ ] Effects finish-off: +** run benchmark/effects checks and record evidence +** conduct explicit maintainer review dialogue (what changed, why, +remaining risks) +* [ ] Release-prep finish-off: +** produce Must/Should/Could summary +** produce immediate corrective/adaptive/perfective next-actions list + +==== Must + +* [ ] Keep required control files at repository root: +** `+.gitignore+`, `+.gitattributes+`, `+.editorconfig+`, +`+.tool-versions+` +** `+Containerfile+` +** `+.containerignore+` (or `+.dockerignore+` only when required for +compatibility) +** `+CNAME+` and `+.nojekyll+` when using GitHub Pages/custom domain +** `+Justfile+` (root by convention) +* [ ] Keep ownership/governance files present: +** `+MAINTAINER+` in root +** `+.github/CODEOWNERS+` +* [ ] Keep machine-readable canonical structure under +`+.machine_readable/+`: +** state/meta/ecosystem files (`+*.a2ml+` or repo standard) +** `+anchors/ANCHOR.a2ml+` +** `+contractiles/+` (`+must+`, `+trust+`, `+lust+`, and related) +** `+ai/+` for AI guidance files +** `+bot_directives/+` for bot control files +* [ ] Keep contractiles/invariants present and wired: +** root `+Mustfile+` (or equivalent) with enforceable checks +** `+Trustfile+` and `+Intentfile+` present +* [ ] Keep security metadata present: +** `+.well-known/security.txt+` and relevant policy metadata +** CI security scanning configured and runnable +* [ ] Keep docs and navigation coherent: +** single navigation entry point in root (`+NAVIGATION.adoc+` or +equivalent) +** no duplicate conflicting docs for same purpose (for example both +`+.md+` and `+.adoc+` in root unless intentionally required) +* [ ] Enforce ABI/FFI purity where the policy applies: +** ABI definitions in Idris2 (`+src/abi/*.idr+`) +** FFI implementations in Zig (`+ffi/**/*.zig+`) +* [ ] Ensure quality gate includes: formatting, lint, unit/integration +tests, p2p/e2e checks, benchmark smoke, docs checks, security scan. + +==== Should + +* [ ] Keep human docs primarily in AsciiDoc (`+.adoc+`) except where +ecosystem rules require other formats (GitHub/community health, legal +text, tool-specific files). +* [ ] Keep non-essential root files moved into structured folders: +** `+docs/+` (theory/practice/whitepapers/proofs/reports) +** `+tests/+` (fixtures/outputs) +** `+licensing/+` (while retaining root `+LICENSE+` when forge detection +needs it) +* [ ] Maintain `+.well-known/+` for public metadata where applicable +(`+security.txt+`, `+humans.txt+`, `+ads.txt+` mirrors if used). +* [ ] Keep CI policy checks for doc-format conventions and canonical +file placement. +* [ ] Keep roadmap/status docs honest with dated evidence. + +==== Could + +* [ ] Maintain both human and machine views of maintenance policy from a +single source (generate one from the other). +* [ ] Add policy bots for corrective/adaptive/perfective/audit modes. +* [ ] Add repo-level architecture map (`+TOPOLOGY.md+`) and +release-readiness dashboards. +* [ ] Add per-repo exception registry for approved policy deviations. + +==== Explicit Root-Placement Rule + +Do *not* move the following out of root if you want default tool +behavior: + +* `+.gitignore+`, `+.gitattributes+`, `+.editorconfig+`, +`+.tool-versions+` +* `+Containerfile+` and ignore file +(`+.containerignore+`/`+.dockerignore+`) +* `+CNAME+` and `+.nojekyll+` for GitHub Pages +* `+Justfile+` + +=== Quick Automated Run (Script) + +Use the helper script first, then use the checklist for deeper/manual +follow-up. + +Script locations: - `+$REPOS_ROOT/run-maintenance.sh+` (set REPOS_ROOT +to your repos directory) - `+~/Desktop/run-maintenance.sh+` + +[source,bash] +---- +~/Desktop/run-maintenance.sh --repo /absolute/path/to/repo --output /tmp/maintenance-report.json +jq . /tmp/maintenance-report.json +---- + +Useful flags: + +[source,bash] +---- +# Strict mode: fail process on failed checks +~/Desktop/run-maintenance.sh --repo /absolute/path/to/repo --strict + +# Skip expensive checks when needed +~/Desktop/run-maintenance.sh --repo /absolute/path/to/repo --skip-panic + +# Explicit language selection +~/Desktop/run-maintenance.sh --repo /absolute/path/to/repo --rust --python + +# Release hard-pass mode (fails on warnings or failures) +~/Desktop/run-maintenance.sh --repo /absolute/path/to/repo --fail-on-warn +---- + +Permission policy in script: - Flags `+g+w/o+w+` files/dirs - Flags +suspicious executable files - Flags shebang scripts missing executable +bit - Supports repo-local exceptions via `+.maintenance-perms-ignore+` +(regex per line) - *Audit-first by default* (non-mutating) - +`+--fix-perms+` is explicit opt-in only (never implicit) - For +reversible local hardening, pair snapshot/restore scripts where +available: - `+scripts/maintenance/perms-state.sh snapshot+` - +`+scripts/maintenance/perms-state.sh lock+` - +`+scripts/maintenance/perms-state.sh restore+` + +Important git behavior: - Git generally tracks execute bit, not full +UNIX mode matrix. - Permission hardening audits do not force +collaborators to re-unlock every file on pull. - Keep lock mode opt-in, +with restore path documented. + +[source,bash] +---- +# Audit-only (recommended default) +~/Desktop/run-maintenance.sh --repo /absolute/path/to/repo + +# Opt-in permission fixes (review output before commit) +~/Desktop/run-maintenance.sh --repo /absolute/path/to/repo --fix-perms +---- + +=== 0) Setup + +[source,bash] +---- +REPO="/absolute/path/to/repo" +cd "$REPO" +---- + +[source,bash] +---- +date -u +git rev-parse --abbrev-ref HEAD +git rev-parse HEAD +git status --porcelain +---- + +=== 1) Preflight + +* [ ] Confirm clean intent: note existing unrelated dirty files before +edits. +* [ ] Confirm runtime/toolchain versions. +* [ ] Confirm container mode expectation (`+podman+`/`+podman-compose+`) +if required. + +[source,bash] +---- +command -v rg git jq || true +command -v podman podman-compose || true +---- + +=== 2) Dependency/Env Prereqs + +* [ ] Python deps in active interpreter (for Python paths). +* [ ] Language-specific tooling installed. + +[source,bash] +---- +python -c "import sys; print(sys.executable)" +python -c "import pydantic; print(pydantic.__version__)" || echo "pydantic missing" +---- + +=== 3) Corrective Maintenance First + +* [ ] Fix regressions, runtime errors, panics, broken commands, failing +tests. +* [ ] Re-run failing checks immediately after each fix. + +=== 4) Code Health Scans + +* [ ] `+TODO/FIXME/XXX/HACK/STUB/PARTIAL+` scan. +* [ ] Permission policy scan (`+g+w/o+w+`, executable hygiene). +* [ ] ABI/FFI policy scan (if applicable: Idris2 ABI, Zig FFI). + +[source,bash] +---- +rg -n "TODO|FIXME|XXX|HACK|STUB|PARTIAL" -g '!**/.git/**' -g '!**/target/**' . +---- + +[source,bash] +---- +# Optional per-repo exceptions (regex per line): +# .maintenance-perms-ignore +# ^vendor/ +# ^third_party/ +---- + +[source,bash] +---- +# Adjust paths for your repo layout +find . -type f \( -name '*.idr' -o -name '*.idris2' -o -name '*.zig' \) +---- + +=== 5) Panic/Safety/Security Pass + +* [ ] Run `+panic-attacker+` assail/assault. +* [ ] Triage findings by severity. +* [ ] Fix high first, then medium. +* [ ] Re-run until acceptable. + +[source,bash] +---- +PANIC_BIN="$(command -v panic-attack || echo "${PANIC_ATTACKER_DIR:-../panic-attacker}/target/release/panic-attack")" +"$PANIC_BIN" assail "$REPO" --output /tmp/assail.json --output-format json --quiet +jq -r '.weak_points | length' /tmp/assail.json +jq -r '.weak_points[] | "\(.severity)|\(.location)|\(.description)"' /tmp/assail.json +---- + +[source,bash] +---- +# If repo has production-only source builder, prefer this for baseline checks: +./scripts/ci/build-panic-assail-source.sh /tmp/panic-src +"$PANIC_BIN" assail /tmp/panic-src --output /tmp/assail-prod.json --output-format json --quiet +---- + +=== 6) Language-Specific Validation + +==== Rust + +* [ ] Format +* [ ] Lint +* [ ] Tests +* [ ] Doc tests +* [ ] Benches (where relevant) + +[source,bash] +---- +cargo fmt --all --check +cargo clippy --workspace --all-targets -- -D warnings +cargo test --workspace +cargo test --workspace --doc +# Optional targeted benchmarks: +cargo bench +---- + +==== Python + +* [ ] Format/lint +* [ ] Type check +* [ ] Tests + +[source,bash] +---- +ruff check . +ruff format --check . +mypy . +pytest -q +---- + +==== Elixir + +* [ ] Format check +* [ ] Lint/static checks +* [ ] Tests + +[source,bash] +---- +mix format --check-formatted +mix credo --strict +mix test +---- + +=== 7) Container/Runtime Checks (Podman) + +* [ ] Build container path. +* [ ] Run smoke tests inside containerized flow. +* [ ] Compare host vs container behavior for parity. + +[source,bash] +---- +podman --version +podman compose version || podman-compose --version +---- + +=== 8) Benchmark + Regression Check + +* [ ] Capture before/after metrics for touched hot paths. +* [ ] Record command + sample size + output. +* [ ] Fail change if critical path regresses beyond threshold. + +=== 9) Adaptive and Perfective Maintenance + +* [ ] Adaptive: compatibility updates (tooling/API/deprecations/config +flags). +* [ ] Perfective: clarity, docs parity, developer workflow improvements. +* [ ] Update roadmap/checklist/docs to match actual implementation +state. + +=== 10) Final QA and Release Hygiene + +* [ ] Re-run full relevant checks one final time. +* [ ] Confirm no unintended file changes. +* [ ] Commit scoped changes with clear message. +* [ ] Push and capture commit SHA. + +[source,bash] +---- +git status --short +git diff --stat +git add +git commit -m "maint: " +git push +---- + +=== 11) Maintenance Report Template + +Copy this block per repo run: + +[source,text] +---- +Repo: +Branch: +Start UTC: +End UTC: + +Scope: +- Corrective: +- Adaptive: +- Perfective: + +Checks Run: +- TODO/FIXME scan: +- Panic-attacker: +- Rust/Python/Elixir checks: +- Container checks: +- Benchmark checks: + +Findings: +- High: +- Medium: +- Low: + +Fixes Applied: +1. +2. +3. + +Validation Results: +- Tests: +- Benchmarks: +- Panic-attacker rerun: + +Artifacts: +- assail report: +- benchmark output: +- logs: + +Commit(s): +- SHA: + +Remaining Risks / Follow-ups: +1. +2. +---- + +=== 12) Language-Repo Additions (Eclexia-Specific) + +Add these checks for language/compiler repositories with formal ABI/FFI +constraints: + +* [x] README structure restored (index/TOC, audience paths, quickstart +sanity). +* [x] Wiki split by audience (laypeople/users/developers) and linked +from docs index. +* [x] Root-level clutter reduced (archive, analysis, reports relegated +to `+docs/+` subtrees). +* [x] Machine-readable docs synchronized (`+STATE.scm+`, `+META.scm+`, +`+ECOSYSTEM.scm+`, contractiles). +* [x] Human-readable docs synchronized (`+README+`, `+QUICK_STATUS+`, +roadmap, wiki home). +* [x] `+Mustfile+` invariants present and enforceable in CI. +* [x] `+Trustfile+` and `+Intentfile+` present and complete. +* [x] FFI/ABI purity policy enforced (`+*.zig+` for FFI, +`+*.idr+`/Idris2 for ABI). +* [x] `+panic-attack+` findings triaged with explicit severity budget +for release. +* [x] Point-to-point, end-to-end, and benchmark checks wired in one +quality gate. +* [x] CI workflows include quality + security + docs checks with +explicit policy. +* [x] Release audit includes corrective/adaptive/perfective + +Must/Should/Could. +* [x] Roadmap/status honesty pass completed (dates and current evidence +updated). + +=== 13) Latest Execution Record (Eclexia, 2026-02-24) + +Repo: `+/tmp/eclexia-releaseprep+` (branch `+release-prep+`, base +`+533ec9e9447f374135cc9e2e81021624ddb3c0ad+`) + +==== 13.1 Setup/Preflight + +* [x] Captured UTC timestamp and git state. +* [x] Tooling presence verified (`+rg+`, `+git+`, `+jq+`, `+cargo+`, +`+rustc+`, `+just+`). +* [x] Runtime/toolchain versions captured. +* [x] Container tooling checked (`+podman+`, `+podman-compose+`). + +==== 13.2 Corrective Maintenance + +* [x] Fixed `+panic-attack+` script path handling (`+mktemp+` output + +local fallback binary detection). +* [x] Removed Idris `+believe_me+` usage from ABI wrappers. +* [x] Fixed conformance crash-noise path by skipping known intentional +stack-overflow case in default runner. +* [x] Re-ran affected checks after each fix. + +==== 13.3 Code-Health Scans + +* [x] TODO/FIXME/STUB/PARTIAL scan run on active code paths. +* [x] ABI/FFI file inventory run (`+*.idr+`, `+*.zig+`). +* [x] Active-code marker count reduced/triaged; remaining items tracked +in release audit. + +==== 13.4 Security/Panic Pass + +* [x] `+panic-attack+` run and triaged. +* [x] Critical findings cleared (Idris unsoundness markers removed). +* [x] Current baseline: 0 weak points (Critical 0, High 0, Medium 0, Low +0). +* [x] High/Medium backlog fully eliminated. + +==== 13.5 Language Validation + +* [x] Final `+just quality-gate+` pass completed (docs, fmt, lint, unit, +conformance, integration, p2p, e2e, bench). +* [x] Additional targeted reruns completed (`+just test-conformance+`, +`+just panic-attack+`, `+just docs-check+`). + +==== 13.6 Adaptive/Perfective/Docs + +* [x] README/wiki/docs structure and indexing restored. +* [x] Root tidy/relegation pass executed. +* [x] Roadmap/status honesty update performed with current date and +evidence links. +* [x] Release audit created with corrective/adaptive/perfective + +Must/Should/Could. +* [x] Full quality-gate rerun passed after hardening updates. +* [x] ABI/FFI extension lane added without breaking stable symbols +(`+ecl_abi_get_info+`, `+ecl_tracker_create_ex+`, +`+ecl_tracker_snapshot+`). +* [x] CI quality workflow now validates sibling `+proven+` repo presence +and critical binding files. +* [x] Proven roadmap now includes explicit "`critical core, not full +rewrite`" adoption guidance and flowchart. + +==== 13.7 Outstanding Items (Explicit) + +* [x] Stable `+v1.0.0+` technical gate readiness met (quality + panic +scan clean). +* [x] Parser/codegen/runtime panic-path hardening completed for +scanner-flagged paths. +* [x] Non-eclexia `+proven+` library checked: already Idris2-first with +Zig ABI bridge; no additional integration changes required in this run. +* [ ] Remote push blocked by token scope: GitHub rejected branch updates +(`+release-prep+`, `+release-prep-pushable+`) due missing `+workflow+` +OAuth scope. + +==== 13.8 Artifacts + +* Release audit: `+docs/reports/V1-READINESS-AUDIT-2026-02-24.md+` +* Panic report: `+/tmp/eclexia-panic-attack.KZ1jpC.json+` (0 weak +points) +* Final quality gate log: `+/tmp/eclexia-quality-gate-final2.log+` (plus +post-change reruns via terminal sessions) +* Local commits: `+88fa2af+` (`+release-prep+`), `+baa3d1c+` +(`+release-prep-pushable+`) + pending new commit from this pass + +=== 12) LLM Operator Instructions + +Use this prompt with an LLM agent when you want the process run +end-to-end: + +[source,text] +---- +Run the maintenance workflow for this repo using MAINTENANCE-CHECKLIST.md. + +Required behavior: +1. Run ~/Desktop/run-maintenance.sh first and collect the JSON report. +2. Triage report results by severity: fail > warn > pass. +3. Execute corrective maintenance first (fix regressions, panics, broken tests/commands). +4. Run TODO/FIXME/stub scan and address relevant items. +5. Run panic-attacker and fix findings in priority order; rerun to confirm. +6. Run language-specific checks (Rust/Python/Elixir) relevant to this repo. +7. Run benchmark/regression checks for touched hot paths. +8. Enforce permission policy: + - no group/world writable source files unless justified + - executable bit only where intended + - use .maintenance-perms-ignore for justified exceptions +9. Update docs/roadmap/checklist entries to reflect actual state. +10. Produce a final report using the template in MAINTENANCE-CHECKLIST.md. + +Constraints: +- Do not revert unrelated existing dirty changes. +- Stage and commit only scoped intended files. +- If blocked, state exactly what is blocked and why. +---- + +=== 13) AI Execution Integrity Contract (Mandatory) + +Use this when delegating maintenance to any AI +(Gemini/Claude/ChatGPT/etc.). + +[source,text] +---- +You must execute this maintenance run with strict integrity. + +Non-negotiable rules: +1. Do not claim any step is complete unless you actually ran it. +2. Do not silently skip checklist items. If skipped, state SKIPPED + exact reason. +3. For every check, provide evidence: + - command executed + - pass/fail/warn + - key output summary + - artifact/log path +4. If a command fails, stop claiming success and report the failure clearly. +5. After each fix, re-run the relevant failing check and report the rerun result. +6. Do not hide uncertainty. If unsure, say so and run additional verification. +7. Never mark “all done” while any fail/warn remains unexplained. +8. Do not make destructive or broad permission changes by default. + - permission changes must be audit-first + - use --fix-perms only with explicit intent +9. Final output must include: + - checklist coverage matrix (each item: PASS/FAIL/WARN/SKIPPED) + - unresolved risks + - exact next actions +10. Prioritize user safety and reputation: no “looks fine” claims without evidence. +---- + +Recommended enforcement line for AI prompts: + +[source,text] +---- +Fail closed: if evidence is missing for any checklist item, treat that item as NOT DONE. +---- + +=== 14) Fleet Enrollment Automation (Gitbot + Hypatia) + +For centralized coverage across existing and new repos: + +[source,bash] +---- +cd "$REPOS_ROOT/gitbot-fleet" +just enroll-repos +---- + +Optional directive write-back to repos that already have +`+.machine_readable/+`: + +[source,bash] +---- +cd "$REPOS_ROOT/gitbot-fleet" +just enroll-repos "$REPOS_ROOT" true +---- + +Release hard gate from fleet: + +[source,bash] +---- +cd "$REPOS_ROOT/gitbot-fleet" +just maintenance-hard-pass /absolute/path/to/repo +---- diff --git a/panel-clades/docs/maintenance/MAINTENANCE-CHECKLIST.md b/panel-clades/docs/maintenance/MAINTENANCE-CHECKLIST.md deleted file mode 100644 index 6889c13f..00000000 --- a/panel-clades/docs/maintenance/MAINTENANCE-CHECKLIST.md +++ /dev/null @@ -1,568 +0,0 @@ -# Maintenance Checklist (Cross-Repo) - -Use this as a repeatable maintenance runbook for any repo. - -Companion policy: - -- `docs/practice/SOFTWARE-DEVELOPMENT-APPROACH.adoc` (human-readable) -- `.machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml` (machine-readable) - -## Canonical Repo Baseline (Final) - -Apply this baseline to every repo unless an explicit exception is recorded. - -### Three-Axis Default Model - -- [ ] Axis 1 (scope priority, runs first): `must > intend > like` -- [ ] Axis 2 (maintenance priority): `corrective > adaptive > perfective` -- [ ] Axis 3 (audit priority): `systems > compliance > effects` -- [ ] Perfective items are derived from Axis 1 honest state (not started independently). - -### Axis 1 Scoping Pass (Mandatory) - -Before Axis 2/3 execution, assemble a scoped worklist from evidence: - -- [ ] Read and reconcile: `README`, roadmap, status docs, maintenance checklist, and current CI/security docs. -- [ ] Scan for unfinished markers: `TODO`, `FIXME`, `XXX`, `HACK`, `STUB`, `PARTIAL`. -- [ ] If Idris is present, scan unsoundness markers: `believe_me`, `assert_total`. -- [ ] Identify declared intent vs actual implementation (docs honesty check). -- [ ] Produce a scope assembly artifact with prioritized entries under: - - `must` (release blockers / safety / correctness) - - `intend` (planned near-term) - - `like` (nice-to-have) - -### Axis 2 Maintenance Execution Rules - -- [ ] Corrective first: fix breakage, defects, regressions, safety issues. -- [ ] Adaptive second: reconcile changed scope, remove stale references, cull no-longer-relevant work. -- [ ] Perfective third: only from current honest state established by Axis 1 and updated by corrective/adaptive actions. - -### Axis 3 Audit Rules - -- [ ] Verify systems are in place and actually operating. -- [ ] Verify documentation explains the real/current state (not aspirational-only), including documented exceptions. -- [ ] Verify safety and security controls are present, active, and evidenced. -- [ ] Verify observed effects/impacts are captured and reviewed. -- [ ] Effects audit includes: - - benchmark execution and recorded results (with before/after where relevant) - - explicit maintainer dialogue/status review on what changed, why, and next risks -- [ ] Audit compliance seams/compromises explicitly: - - policy exceptions are recorded with rationale, scope, and expiry/review - - exception does not silently broaden into general policy drift - - language-policy contamination checks run (example: a single TS exception must not trigger broad TypeScript conversion) - - run `panic-attack` as the compliance-audit scanner - - run ecological checking under effects (using sustainabot guidance as current baseline) - -### Generic Cleanup And Finish-Off Pass - -Run this pass at the end of a corrective/adaptive/perfective cycle: - -- [ ] Root cleanup: - - keep only required control/entry files in root - - move non-essential docs/reports/fixtures to canonical folders -- [ ] Remove or archive stale work: - - close out completed TODO/STUB/PARTIAL items - - cull obsolete references, dead files, and superseded plans -- [ ] Documentation finish-off: - - ensure README, roadmap, status, and wiki match actual implementation state - - ensure machine-readable policy/state files match human docs -- [ ] Security/compliance finish-off: - - run compliance scanner (`panic-attack`) and resolve high-priority findings - - verify exception register and seams/compromises are explicitly bounded -- [ ] Effects finish-off: - - run benchmark/effects checks and record evidence - - conduct explicit maintainer review dialogue (what changed, why, remaining risks) -- [ ] Release-prep finish-off: - - produce Must/Should/Could summary - - produce immediate corrective/adaptive/perfective next-actions list - -### Must - -- [ ] Keep required control files at repository root: - - `.gitignore`, `.gitattributes`, `.editorconfig`, `.tool-versions` - - `Containerfile` - - `.containerignore` (or `.dockerignore` only when required for compatibility) - - `CNAME` and `.nojekyll` when using GitHub Pages/custom domain - - `Justfile` (root by convention) -- [ ] Keep ownership/governance files present: - - `MAINTAINER` in root - - `.github/CODEOWNERS` -- [ ] Keep machine-readable canonical structure under `.machine_readable/`: - - state/meta/ecosystem files (`*.a2ml` or repo standard) - - `anchors/ANCHOR.a2ml` - - `contractiles/` (`must`, `trust`, `lust`, and related) - - `ai/` for AI guidance files - - `bot_directives/` for bot control files -- [ ] Keep contractiles/invariants present and wired: - - root `Mustfile` (or equivalent) with enforceable checks - - `Trustfile` and `Intentfile` present -- [ ] Keep security metadata present: - - `.well-known/security.txt` and relevant policy metadata - - CI security scanning configured and runnable -- [ ] Keep docs and navigation coherent: - - single navigation entry point in root (`NAVIGATION.adoc` or equivalent) - - no duplicate conflicting docs for same purpose (for example both `.md` and `.adoc` in root unless intentionally required) -- [ ] Enforce ABI/FFI purity where the policy applies: - - ABI definitions in Idris2 (`src/abi/*.idr`) - - FFI implementations in Zig (`ffi/**/*.zig`) -- [ ] Ensure quality gate includes: formatting, lint, unit/integration tests, p2p/e2e checks, benchmark smoke, docs checks, security scan. - -### Should - -- [ ] Keep human docs primarily in AsciiDoc (`.adoc`) except where ecosystem rules require other formats (GitHub/community health, legal text, tool-specific files). -- [ ] Keep non-essential root files moved into structured folders: - - `docs/` (theory/practice/whitepapers/proofs/reports) - - `tests/` (fixtures/outputs) - - `licensing/` (while retaining root `LICENSE` when forge detection needs it) -- [ ] Maintain `.well-known/` for public metadata where applicable (`security.txt`, `humans.txt`, `ads.txt` mirrors if used). -- [ ] Keep CI policy checks for doc-format conventions and canonical file placement. -- [ ] Keep roadmap/status docs honest with dated evidence. - -### Could - -- [ ] Maintain both human and machine views of maintenance policy from a single source (generate one from the other). -- [ ] Add policy bots for corrective/adaptive/perfective/audit modes. -- [ ] Add repo-level architecture map (`TOPOLOGY.md`) and release-readiness dashboards. -- [ ] Add per-repo exception registry for approved policy deviations. - -### Explicit Root-Placement Rule - -Do **not** move the following out of root if you want default tool behavior: - -- `.gitignore`, `.gitattributes`, `.editorconfig`, `.tool-versions` -- `Containerfile` and ignore file (`.containerignore`/`.dockerignore`) -- `CNAME` and `.nojekyll` for GitHub Pages -- `Justfile` - -## Quick Automated Run (Script) - -Use the helper script first, then use the checklist for deeper/manual follow-up. - -Script locations: -- `$REPOS_ROOT/run-maintenance.sh` (set REPOS_ROOT to your repos directory) -- `~/Desktop/run-maintenance.sh` - -```bash -~/Desktop/run-maintenance.sh --repo /absolute/path/to/repo --output /tmp/maintenance-report.json -jq . /tmp/maintenance-report.json -``` - -Useful flags: - -```bash -# Strict mode: fail process on failed checks -~/Desktop/run-maintenance.sh --repo /absolute/path/to/repo --strict - -# Skip expensive checks when needed -~/Desktop/run-maintenance.sh --repo /absolute/path/to/repo --skip-panic - -# Explicit language selection -~/Desktop/run-maintenance.sh --repo /absolute/path/to/repo --rust --python - -# Release hard-pass mode (fails on warnings or failures) -~/Desktop/run-maintenance.sh --repo /absolute/path/to/repo --fail-on-warn -``` - -Permission policy in script: -- Flags `g+w/o+w` files/dirs -- Flags suspicious executable files -- Flags shebang scripts missing executable bit -- Supports repo-local exceptions via `.maintenance-perms-ignore` (regex per line) -- **Audit-first by default** (non-mutating) -- `--fix-perms` is explicit opt-in only (never implicit) -- For reversible local hardening, pair snapshot/restore scripts where available: - - `scripts/maintenance/perms-state.sh snapshot` - - `scripts/maintenance/perms-state.sh lock` - - `scripts/maintenance/perms-state.sh restore` - -Important git behavior: -- Git generally tracks execute bit, not full UNIX mode matrix. -- Permission hardening audits do not force collaborators to re-unlock every file on pull. -- Keep lock mode opt-in, with restore path documented. - -```bash -# Audit-only (recommended default) -~/Desktop/run-maintenance.sh --repo /absolute/path/to/repo - -# Opt-in permission fixes (review output before commit) -~/Desktop/run-maintenance.sh --repo /absolute/path/to/repo --fix-perms -``` - -## 0) Setup - -```bash -REPO="/absolute/path/to/repo" -cd "$REPO" -``` - -```bash -date -u -git rev-parse --abbrev-ref HEAD -git rev-parse HEAD -git status --porcelain -``` - -## 1) Preflight - -- [ ] Confirm clean intent: note existing unrelated dirty files before edits. -- [ ] Confirm runtime/toolchain versions. -- [ ] Confirm container mode expectation (`podman`/`podman-compose`) if required. - -```bash -command -v rg git jq || true -command -v podman podman-compose || true -``` - -## 2) Dependency/Env Prereqs - -- [ ] Python deps in active interpreter (for Python paths). -- [ ] Language-specific tooling installed. - -```bash -python -c "import sys; print(sys.executable)" -python -c "import pydantic; print(pydantic.__version__)" || echo "pydantic missing" -``` - -## 3) Corrective Maintenance First - -- [ ] Fix regressions, runtime errors, panics, broken commands, failing tests. -- [ ] Re-run failing checks immediately after each fix. - -## 4) Code Health Scans - -- [ ] `TODO/FIXME/XXX/HACK/STUB/PARTIAL` scan. -- [ ] Permission policy scan (`g+w/o+w`, executable hygiene). -- [ ] ABI/FFI policy scan (if applicable: Idris2 ABI, Zig FFI). - -```bash -rg -n "TODO|FIXME|XXX|HACK|STUB|PARTIAL" -g '!**/.git/**' -g '!**/target/**' . -``` - -```bash -# Optional per-repo exceptions (regex per line): -# .maintenance-perms-ignore -# ^vendor/ -# ^third_party/ -``` - -```bash -# Adjust paths for your repo layout -find . -type f \( -name '*.idr' -o -name '*.idris2' -o -name '*.zig' \) -``` - -## 5) Panic/Safety/Security Pass - -- [ ] Run `panic-attacker` assail/assault. -- [ ] Triage findings by severity. -- [ ] Fix high first, then medium. -- [ ] Re-run until acceptable. - -```bash -PANIC_BIN="$(command -v panic-attack || echo "${PANIC_ATTACKER_DIR:-../panic-attacker}/target/release/panic-attack")" -"$PANIC_BIN" assail "$REPO" --output /tmp/assail.json --output-format json --quiet -jq -r '.weak_points | length' /tmp/assail.json -jq -r '.weak_points[] | "\(.severity)|\(.location)|\(.description)"' /tmp/assail.json -``` - -```bash -# If repo has production-only source builder, prefer this for baseline checks: -./scripts/ci/build-panic-assail-source.sh /tmp/panic-src -"$PANIC_BIN" assail /tmp/panic-src --output /tmp/assail-prod.json --output-format json --quiet -``` - -## 6) Language-Specific Validation - -### Rust - -- [ ] Format -- [ ] Lint -- [ ] Tests -- [ ] Doc tests -- [ ] Benches (where relevant) - -```bash -cargo fmt --all --check -cargo clippy --workspace --all-targets -- -D warnings -cargo test --workspace -cargo test --workspace --doc -# Optional targeted benchmarks: -cargo bench -``` - -### Python - -- [ ] Format/lint -- [ ] Type check -- [ ] Tests - -```bash -ruff check . -ruff format --check . -mypy . -pytest -q -``` - -### Elixir - -- [ ] Format check -- [ ] Lint/static checks -- [ ] Tests - -```bash -mix format --check-formatted -mix credo --strict -mix test -``` - -## 7) Container/Runtime Checks (Podman) - -- [ ] Build container path. -- [ ] Run smoke tests inside containerized flow. -- [ ] Compare host vs container behavior for parity. - -```bash -podman --version -podman compose version || podman-compose --version -``` - -## 8) Benchmark + Regression Check - -- [ ] Capture before/after metrics for touched hot paths. -- [ ] Record command + sample size + output. -- [ ] Fail change if critical path regresses beyond threshold. - -## 9) Adaptive and Perfective Maintenance - -- [ ] Adaptive: compatibility updates (tooling/API/deprecations/config flags). -- [ ] Perfective: clarity, docs parity, developer workflow improvements. -- [ ] Update roadmap/checklist/docs to match actual implementation state. - -## 10) Final QA and Release Hygiene - -- [ ] Re-run full relevant checks one final time. -- [ ] Confirm no unintended file changes. -- [ ] Commit scoped changes with clear message. -- [ ] Push and capture commit SHA. - -```bash -git status --short -git diff --stat -git add -git commit -m "maint: " -git push -``` - -## 11) Maintenance Report Template - -Copy this block per repo run: - -```text -Repo: -Branch: -Start UTC: -End UTC: - -Scope: -- Corrective: -- Adaptive: -- Perfective: - -Checks Run: -- TODO/FIXME scan: -- Panic-attacker: -- Rust/Python/Elixir checks: -- Container checks: -- Benchmark checks: - -Findings: -- High: -- Medium: -- Low: - -Fixes Applied: -1. -2. -3. - -Validation Results: -- Tests: -- Benchmarks: -- Panic-attacker rerun: - -Artifacts: -- assail report: -- benchmark output: -- logs: - -Commit(s): -- SHA: - -Remaining Risks / Follow-ups: -1. -2. -``` - -## 12) Language-Repo Additions (Eclexia-Specific) - -Add these checks for language/compiler repositories with formal ABI/FFI constraints: - -- [x] README structure restored (index/TOC, audience paths, quickstart sanity). -- [x] Wiki split by audience (laypeople/users/developers) and linked from docs index. -- [x] Root-level clutter reduced (archive, analysis, reports relegated to `docs/` subtrees). -- [x] Machine-readable docs synchronized (`STATE.scm`, `META.scm`, `ECOSYSTEM.scm`, contractiles). -- [x] Human-readable docs synchronized (`README`, `QUICK_STATUS`, roadmap, wiki home). -- [x] `Mustfile` invariants present and enforceable in CI. -- [x] `Trustfile` and `Intentfile` present and complete. -- [x] FFI/ABI purity policy enforced (`*.zig` for FFI, `*.idr`/Idris2 for ABI). -- [x] `panic-attack` findings triaged with explicit severity budget for release. -- [x] Point-to-point, end-to-end, and benchmark checks wired in one quality gate. -- [x] CI workflows include quality + security + docs checks with explicit policy. -- [x] Release audit includes corrective/adaptive/perfective + Must/Should/Could. -- [x] Roadmap/status honesty pass completed (dates and current evidence updated). - -## 13) Latest Execution Record (Eclexia, 2026-02-24) - -Repo: `/tmp/eclexia-releaseprep` (branch `release-prep`, base `533ec9e9447f374135cc9e2e81021624ddb3c0ad`) - -### 13.1 Setup/Preflight - -- [x] Captured UTC timestamp and git state. -- [x] Tooling presence verified (`rg`, `git`, `jq`, `cargo`, `rustc`, `just`). -- [x] Runtime/toolchain versions captured. -- [x] Container tooling checked (`podman`, `podman-compose`). - -### 13.2 Corrective Maintenance - -- [x] Fixed `panic-attack` script path handling (`mktemp` output + local fallback binary detection). -- [x] Removed Idris `believe_me` usage from ABI wrappers. -- [x] Fixed conformance crash-noise path by skipping known intentional stack-overflow case in default runner. -- [x] Re-ran affected checks after each fix. - -### 13.3 Code-Health Scans - -- [x] TODO/FIXME/STUB/PARTIAL scan run on active code paths. -- [x] ABI/FFI file inventory run (`*.idr`, `*.zig`). -- [x] Active-code marker count reduced/triaged; remaining items tracked in release audit. - -### 13.4 Security/Panic Pass - -- [x] `panic-attack` run and triaged. -- [x] Critical findings cleared (Idris unsoundness markers removed). -- [x] Current baseline: 0 weak points (Critical 0, High 0, Medium 0, Low 0). -- [x] High/Medium backlog fully eliminated. - -### 13.5 Language Validation - -- [x] Final `just quality-gate` pass completed (docs, fmt, lint, unit, conformance, integration, p2p, e2e, bench). -- [x] Additional targeted reruns completed (`just test-conformance`, `just panic-attack`, `just docs-check`). - -### 13.6 Adaptive/Perfective/Docs - -- [x] README/wiki/docs structure and indexing restored. -- [x] Root tidy/relegation pass executed. -- [x] Roadmap/status honesty update performed with current date and evidence links. -- [x] Release audit created with corrective/adaptive/perfective + Must/Should/Could. -- [x] Full quality-gate rerun passed after hardening updates. -- [x] ABI/FFI extension lane added without breaking stable symbols (`ecl_abi_get_info`, `ecl_tracker_create_ex`, `ecl_tracker_snapshot`). -- [x] CI quality workflow now validates sibling `proven` repo presence and critical binding files. -- [x] Proven roadmap now includes explicit "critical core, not full rewrite" adoption guidance and flowchart. - -### 13.7 Outstanding Items (Explicit) - -- [x] Stable `v1.0.0` technical gate readiness met (quality + panic scan clean). -- [x] Parser/codegen/runtime panic-path hardening completed for scanner-flagged paths. -- [x] Non-eclexia `proven` library checked: already Idris2-first with Zig ABI bridge; no additional integration changes required in this run. -- [ ] Remote push blocked by token scope: GitHub rejected branch updates (`release-prep`, `release-prep-pushable`) due missing `workflow` OAuth scope. - -### 13.8 Artifacts - -- Release audit: `docs/reports/V1-READINESS-AUDIT-2026-02-24.md` -- Panic report: `/tmp/eclexia-panic-attack.KZ1jpC.json` (0 weak points) -- Final quality gate log: `/tmp/eclexia-quality-gate-final2.log` (plus post-change reruns via terminal sessions) -- Local commits: `88fa2af` (`release-prep`), `baa3d1c` (`release-prep-pushable`) + pending new commit from this pass - -## 12) LLM Operator Instructions - -Use this prompt with an LLM agent when you want the process run end-to-end: - -```text -Run the maintenance workflow for this repo using MAINTENANCE-CHECKLIST.md. - -Required behavior: -1. Run ~/Desktop/run-maintenance.sh first and collect the JSON report. -2. Triage report results by severity: fail > warn > pass. -3. Execute corrective maintenance first (fix regressions, panics, broken tests/commands). -4. Run TODO/FIXME/stub scan and address relevant items. -5. Run panic-attacker and fix findings in priority order; rerun to confirm. -6. Run language-specific checks (Rust/Python/Elixir) relevant to this repo. -7. Run benchmark/regression checks for touched hot paths. -8. Enforce permission policy: - - no group/world writable source files unless justified - - executable bit only where intended - - use .maintenance-perms-ignore for justified exceptions -9. Update docs/roadmap/checklist entries to reflect actual state. -10. Produce a final report using the template in MAINTENANCE-CHECKLIST.md. - -Constraints: -- Do not revert unrelated existing dirty changes. -- Stage and commit only scoped intended files. -- If blocked, state exactly what is blocked and why. -``` - -## 13) AI Execution Integrity Contract (Mandatory) - -Use this when delegating maintenance to any AI (Gemini/Claude/ChatGPT/etc.). - -```text -You must execute this maintenance run with strict integrity. - -Non-negotiable rules: -1. Do not claim any step is complete unless you actually ran it. -2. Do not silently skip checklist items. If skipped, state SKIPPED + exact reason. -3. For every check, provide evidence: - - command executed - - pass/fail/warn - - key output summary - - artifact/log path -4. If a command fails, stop claiming success and report the failure clearly. -5. After each fix, re-run the relevant failing check and report the rerun result. -6. Do not hide uncertainty. If unsure, say so and run additional verification. -7. Never mark “all done” while any fail/warn remains unexplained. -8. Do not make destructive or broad permission changes by default. - - permission changes must be audit-first - - use --fix-perms only with explicit intent -9. Final output must include: - - checklist coverage matrix (each item: PASS/FAIL/WARN/SKIPPED) - - unresolved risks - - exact next actions -10. Prioritize user safety and reputation: no “looks fine” claims without evidence. -``` - -Recommended enforcement line for AI prompts: - -```text -Fail closed: if evidence is missing for any checklist item, treat that item as NOT DONE. -``` - -## 14) Fleet Enrollment Automation (Gitbot + Hypatia) - -For centralized coverage across existing and new repos: - -```bash -cd "$REPOS_ROOT/gitbot-fleet" -just enroll-repos -``` - -Optional directive write-back to repos that already have `.machine_readable/`: - -```bash -cd "$REPOS_ROOT/gitbot-fleet" -just enroll-repos "$REPOS_ROOT" true -``` - -Release hard gate from fleet: - -```bash -cd "$REPOS_ROOT/gitbot-fleet" -just maintenance-hard-pass /absolute/path/to/repo -``` diff --git a/panel-clades/src/abi/README.adoc b/panel-clades/src/abi/README.adoc new file mode 100644 index 00000000..da8cce1a --- /dev/null +++ b/panel-clades/src/abi/README.adoc @@ -0,0 +1,58 @@ +== panel-clades/src/abi/ — Idris2 ABI Formal Proofs + +=== Purpose + +Formal verification of the panel-clades C ABI using Idris2 dependent +types. Proves memory layout correctness, alignment properties, and type +safety for the Zig FFI layer. + +=== Boundary + +* *Verified by*: Idris2 0.8.0 type checker +* *Implemented by*: `+panel-clades/ffi/zig/+` (Zig FFI matching these +proofs) +* *Generated output*: `+generated/abi/*.h+` (C headers from ABI +definitions) + +=== Files + +[width="100%",cols="40%,60%",options="header",] +|=== +|File |Purpose +|`+Types.idr+` |Core ABI types: Platform, CladeKind, Result, Handle with +proofs + +|`+Layout.idr+` |Memory layout proofs: alignment, struct sizing, C ABI +compliance + +|`+Foreign.idr+` |FFI function declarations with type signatures +|=== + +=== Invariants + +* `+%default total+` — all functions must be provably total +* 0 `+believe_me+` — no unsafe escape hatches +* 0 `+assert_total+` — no totality bypasses +* Proofs use `+So+` witnesses, `+Divides+` proofs, and `+DivideBy+` +constructors +* CladeKind exhaustiveness proven via vector-based witnesses (13 +variants) + +=== Proof Status (v0.2.0) + +* `+fieldsAlignedProof+`: CLOSED — recursive proof via +`+proveFieldsAligned+` +* `+exampleFieldsAligned+`: CLOSED — concrete proof for 3-field example +layout +* `+offsetInBoundsProof+`: CLOSED — runtime boolean check (no Elem +witness needed) + +=== Adding New Proofs + +[arabic] +. Define types in `+Types.idr+` with appropriate indices +. Write layout proofs in `+Layout.idr+` using `+FieldsAligned+` and +`+CABICompliant+` +. Declare FFI functions in `+Foreign.idr+` +. Verify with `+idris2 --check+` (requires `+.ipkg+` — currently +missing) diff --git a/panel-clades/src/abi/README.md b/panel-clades/src/abi/README.md deleted file mode 100644 index 27548bca..00000000 --- a/panel-clades/src/abi/README.md +++ /dev/null @@ -1,40 +0,0 @@ -# panel-clades/src/abi/ — Idris2 ABI Formal Proofs - -## Purpose - -Formal verification of the panel-clades C ABI using Idris2 dependent types. Proves memory layout correctness, alignment properties, and type safety for the Zig FFI layer. - -## Boundary - -- **Verified by**: Idris2 0.8.0 type checker -- **Implemented by**: `panel-clades/ffi/zig/` (Zig FFI matching these proofs) -- **Generated output**: `generated/abi/*.h` (C headers from ABI definitions) - -## Files - -| File | Purpose | -|------|---------| -| `Types.idr` | Core ABI types: Platform, CladeKind, Result, Handle with proofs | -| `Layout.idr` | Memory layout proofs: alignment, struct sizing, C ABI compliance | -| `Foreign.idr` | FFI function declarations with type signatures | - -## Invariants - -- `%default total` — all functions must be provably total -- 0 `believe_me` — no unsafe escape hatches -- 0 `assert_total` — no totality bypasses -- Proofs use `So` witnesses, `Divides` proofs, and `DivideBy` constructors -- CladeKind exhaustiveness proven via vector-based witnesses (13 variants) - -## Proof Status (v0.2.0) - -- `fieldsAlignedProof`: CLOSED — recursive proof via `proveFieldsAligned` -- `exampleFieldsAligned`: CLOSED — concrete proof for 3-field example layout -- `offsetInBoundsProof`: CLOSED — runtime boolean check (no Elem witness needed) - -## Adding New Proofs - -1. Define types in `Types.idr` with appropriate indices -2. Write layout proofs in `Layout.idr` using `FieldsAligned` and `CABICompliant` -3. Declare FFI functions in `Foreign.idr` -4. Verify with `idris2 --check` (requires `.ipkg` — currently missing) diff --git a/src-gossamer/src/README.adoc b/src-gossamer/src/README.adoc new file mode 100644 index 00000000..cb093053 --- /dev/null +++ b/src-gossamer/src/README.adoc @@ -0,0 +1,63 @@ +== src-gossamer/src/ — Rust Backend Modules + +=== Purpose + +The Gossamer-native backend for PanLL. Replaces the former Tauri 2.0 +backend. Contains 40+ domain modules registered as IPC command handlers +in `+main.rs+`. All commands are invoked from the ReScript frontend via +`+RuntimeBridge.invoke+`. + +=== Boundary + +* *Exposes*: IPC commands via `+app.command("name", |payload| { ... })+` +* *Consumed by*: ReScript frontend through `+window.__gossamer_invoke+` +* *Dependencies*: `+reqwest+` (HTTP), `+serde_json+` (JSON), +`+gossamer-rs+` (runtime) + +=== Key Files + +[width="100%",cols="40%,60%",options="header",] +|=== +|File |Purpose +|`+main.rs+` |Command registration hub (100+ handlers) + +|`+http_client.rs+` |Shared async/blocking HTTP client infrastructure + +|`+verisim_live.rs+` |VeriSimDB connection (health, octads, VCL, state +persistence) + +|`+echidna_live.rs+` |ECHIDNA theorem prover connection + +|`+boj_live.rs+` |BoJ cartridge server connection + +|`+service_registry.rs+` |Centralized service lifecycle (v0.2.0) + +|`+settings.rs+` |User settings persistence (v0.2.0) + +|`+identity.rs+` |Identity snapshots and team replication (v0.2.0) + +|`+compat.rs+` |Tauri → Gossamer AppHandle shim + +|`+groove.rs+` |Groove agent execution kernel +|=== + +=== Command Registration Pattern + +[source,rust] +---- +app.command("command_name", |payload| { + let arg = get_str(&payload, "field")?; + result_to_json(module::function(arg)) +}); +---- + +=== Invariants + +* All service URLs respect environment variables (`+VERISIMDB_URL+`, +`+ECHIDNA_URL+`, etc.) +* Blocking commands use `+reqwest::blocking::Client+` (inline commands +in main.rs) +* Async commands use the `+http_client+` module’s `+ServiceEndpoint+` + +async functions +* New modules: declare `+mod xxx;+` in main.rs, register commands, add +to this README diff --git a/src-gossamer/src/README.md b/src-gossamer/src/README.md deleted file mode 100644 index 133d259f..00000000 --- a/src-gossamer/src/README.md +++ /dev/null @@ -1,42 +0,0 @@ -# src-gossamer/src/ — Rust Backend Modules - -## Purpose - -The Gossamer-native backend for PanLL. Replaces the former Tauri 2.0 backend. Contains 40+ domain modules registered as IPC command handlers in `main.rs`. All commands are invoked from the ReScript frontend via `RuntimeBridge.invoke`. - -## Boundary - -- **Exposes**: IPC commands via `app.command("name", |payload| { ... })` -- **Consumed by**: ReScript frontend through `window.__gossamer_invoke` -- **Dependencies**: `reqwest` (HTTP), `serde_json` (JSON), `gossamer-rs` (runtime) - -## Key Files - -| File | Purpose | -|------|---------| -| `main.rs` | Command registration hub (100+ handlers) | -| `http_client.rs` | Shared async/blocking HTTP client infrastructure | -| `verisim_live.rs` | VeriSimDB connection (health, octads, VCL, state persistence) | -| `echidna_live.rs` | ECHIDNA theorem prover connection | -| `boj_live.rs` | BoJ cartridge server connection | -| `service_registry.rs` | Centralized service lifecycle (v0.2.0) | -| `settings.rs` | User settings persistence (v0.2.0) | -| `identity.rs` | Identity snapshots and team replication (v0.2.0) | -| `compat.rs` | Tauri → Gossamer AppHandle shim | -| `groove.rs` | Groove agent execution kernel | - -## Command Registration Pattern - -```rust -app.command("command_name", |payload| { - let arg = get_str(&payload, "field")?; - result_to_json(module::function(arg)) -}); -``` - -## Invariants - -- All service URLs respect environment variables (`VERISIMDB_URL`, `ECHIDNA_URL`, etc.) -- Blocking commands use `reqwest::blocking::Client` (inline commands in main.rs) -- Async commands use the `http_client` module's `ServiceEndpoint` + async functions -- New modules: declare `mod xxx;` in main.rs, register commands, add to this README diff --git a/src/abi/README.adoc b/src/abi/README.adoc new file mode 100644 index 00000000..7e5cf317 --- /dev/null +++ b/src/abi/README.adoc @@ -0,0 +1,35 @@ +== src/abi/ — ABI Schema Definitions + +SPDX-License-Identifier: CC-BY-SA-4.0 + +This directory contains the *source-of-truth ABI schemas* that define +the contract between PanLL and external systems (primarily the BoJ +cartridge server). + +=== Files + +* *cartridge-schema.json* — Complete BoJ cartridge ABI schema extracted +from Idris2 ABI definitions + Zig FFI exports + V-lang adapter +endpoints. Defines all 21 cartridges, their tools, parameters, states, +protocols, and tiers. + +=== How It’s Used + +[arabic] +. *CartridgeAbi.res* (in `+src/generated/+`) is generated from this +schema +. *ppx_typell* validates compile-time invocations against this schema +. *Seam tests* (in `+tests/cartridge_abi_seam_test.js+`) validate that +CartridgeAbi.res matches this schema at test time +. *BoJ seams.zig* (in boj-server) validates the BoJ catalogue matches +the cartridge count and protocol assignments declared here + +=== Regeneration + +[source,bash] +---- +deno task gen:cartridge-abi +---- + +This reads `+cartridge-schema.json+` and regenerates +`+src/generated/CartridgeAbi.res+`. diff --git a/src/abi/README.md b/src/abi/README.md deleted file mode 100644 index 810819be..00000000 --- a/src/abi/README.md +++ /dev/null @@ -1,29 +0,0 @@ -# src/abi/ — ABI Schema Definitions - -SPDX-License-Identifier: CC-BY-SA-4.0 - -This directory contains the **source-of-truth ABI schemas** that define the -contract between PanLL and external systems (primarily the BoJ cartridge server). - -## Files - -- **cartridge-schema.json** — Complete BoJ cartridge ABI schema extracted from - Idris2 ABI definitions + Zig FFI exports + V-lang adapter endpoints. Defines - all 21 cartridges, their tools, parameters, states, protocols, and tiers. - -## How It's Used - -1. **CartridgeAbi.res** (in `src/generated/`) is generated from this schema -2. **ppx_typell** validates compile-time invocations against this schema -3. **Seam tests** (in `tests/cartridge_abi_seam_test.js`) validate that - CartridgeAbi.res matches this schema at test time -4. **BoJ seams.zig** (in boj-server) validates the BoJ catalogue matches - the cartridge count and protocol assignments declared here - -## Regeneration - -```bash -deno task gen:cartridge-abi -``` - -This reads `cartridge-schema.json` and regenerates `src/generated/CartridgeAbi.res`. diff --git a/src/commands/README.adoc b/src/commands/README.adoc new file mode 100644 index 00000000..7893c41c --- /dev/null +++ b/src/commands/README.adoc @@ -0,0 +1,48 @@ +== src/commands/ — Gossamer Bridge Commands + +=== Purpose + +Contains TEA command wrappers that invoke backend operations through the +Gossamer IPC bridge (`+RuntimeBridge.invoke+`). Each module provides +functions that return `+Tea_Cmd.t<'msg>+` for use in sub-updaters. + +=== Boundary + +* *Imports*: `+RuntimeBridge+` (for `+invoke+`), domain-specific types +* *Used by*: `+src/update/+` sub-updaters +* *Dependency direction*: commands → RuntimeBridge → Gossamer backend + +=== Invariants + +* All commands follow the `+Tea_Cmd.call+` + `+invoke+` + +`+Promise.then/catch+` pattern +* Success routes through `+tagger(Ok(result))+`, failure through +`+tagger(Error(message))+` +* Never throw synchronously — always use `+Promise.catch+` for error +handling +* Use `+ErrorBoundary.invokeWithBoundary+` for new commands (v0.2.0+) + +=== Naming Convention + +`+{Domain}Cmd.res+` — e.g. `+ServiceCmd.res+`, `+SettingsCmd.res+`, +`+GossamerCmd.res+` + +=== Standard Command Pattern + +[source,rescript] +---- +let myCommand = (arg: string, tagger: result => 'msg): Tea_Cmd.t<'msg> => { + Tea_Cmd.call(callbacks => { + RuntimeBridge.invoke("backend_command_name", {"arg": arg}) + ->Promise.then(result => { + callbacks.enqueue(tagger(Ok(result))) + Promise.resolve() + }) + ->Promise.catch(_err => { + callbacks.enqueue(tagger(Error("Human-readable error context"))) + Promise.resolve() + }) + ->ignore + }) +} +---- diff --git a/src/commands/README.md b/src/commands/README.md deleted file mode 100644 index 7f660161..00000000 --- a/src/commands/README.md +++ /dev/null @@ -1,41 +0,0 @@ -# src/commands/ — Gossamer Bridge Commands - -## Purpose - -Contains TEA command wrappers that invoke backend operations through the Gossamer IPC bridge (`RuntimeBridge.invoke`). Each module provides functions that return `Tea_Cmd.t<'msg>` for use in sub-updaters. - -## Boundary - -- **Imports**: `RuntimeBridge` (for `invoke`), domain-specific types -- **Used by**: `src/update/` sub-updaters -- **Dependency direction**: commands → RuntimeBridge → Gossamer backend - -## Invariants - -- All commands follow the `Tea_Cmd.call` + `invoke` + `Promise.then/catch` pattern -- Success routes through `tagger(Ok(result))`, failure through `tagger(Error(message))` -- Never throw synchronously — always use `Promise.catch` for error handling -- Use `ErrorBoundary.invokeWithBoundary` for new commands (v0.2.0+) - -## Naming Convention - -`{Domain}Cmd.res` — e.g. `ServiceCmd.res`, `SettingsCmd.res`, `GossamerCmd.res` - -## Standard Command Pattern - -```rescript -let myCommand = (arg: string, tagger: result => 'msg): Tea_Cmd.t<'msg> => { - Tea_Cmd.call(callbacks => { - RuntimeBridge.invoke("backend_command_name", {"arg": arg}) - ->Promise.then(result => { - callbacks.enqueue(tagger(Ok(result))) - Promise.resolve() - }) - ->Promise.catch(_err => { - callbacks.enqueue(tagger(Error("Human-readable error context"))) - Promise.resolve() - }) - ->ignore - }) -} -``` diff --git a/src/components/README.adoc b/src/components/README.adoc new file mode 100644 index 00000000..bbce62db --- /dev/null +++ b/src/components/README.adoc @@ -0,0 +1,28 @@ +== src/components/ — Panel View Components + +=== Purpose + +Contains the view functions for all 108 PanLL panels. Each component +renders a panel’s UI using the custom TEA virtual DOM (`+Tea_Html+`). +Components are pure functions: `+model -> Tea_Html.t+`. + +=== Boundary + +* *Imports*: `+Model+`, `+Msg+`, `+Tea_Html+`, `+Attrs+`, `+Events+` +* *Used by*: `+View.res+` (the main view dispatcher) +* *Does NOT import*: `+Update+`, `+Storage+`, `+RuntimeBridge+`, or +commands + +=== Invariants + +* Components are pure view functions — no side effects, no state +mutation +* Use `+list{}+` for vdom children: `+Tea_Html.div(list{}, list{...})+` +* Use `+Events.onClick+` / `+Events.onInput+` for event handlers +* Say "`panel`" never "`pane`" in all labels and comments +* All components must support keyboard navigation (`+onActivate+` +callback) + +=== Naming Convention + +`+{PanelName}.res+` — matches the panel name in the panel switcher. diff --git a/src/components/README.md b/src/components/README.md deleted file mode 100644 index 416a5d11..00000000 --- a/src/components/README.md +++ /dev/null @@ -1,23 +0,0 @@ -# src/components/ — Panel View Components - -## Purpose - -Contains the view functions for all 108 PanLL panels. Each component renders a panel's UI using the custom TEA virtual DOM (`Tea_Html`). Components are pure functions: `model -> Tea_Html.t`. - -## Boundary - -- **Imports**: `Model`, `Msg`, `Tea_Html`, `Attrs`, `Events` -- **Used by**: `View.res` (the main view dispatcher) -- **Does NOT import**: `Update`, `Storage`, `RuntimeBridge`, or commands - -## Invariants - -- Components are pure view functions — no side effects, no state mutation -- Use `list{}` for vdom children: `Tea_Html.div(list{}, list{...})` -- Use `Events.onClick` / `Events.onInput` for event handlers -- Say "panel" never "pane" in all labels and comments -- All components must support keyboard navigation (`onActivate` callback) - -## Naming Convention - -`{PanelName}.res` — matches the panel name in the panel switcher. diff --git a/src/core/README.adoc b/src/core/README.adoc new file mode 100644 index 00000000..4c580bf8 --- /dev/null +++ b/src/core/README.adoc @@ -0,0 +1,46 @@ +== src/core/ — Domain Engines + +=== Purpose + +Contains pure business logic engines that operate on model state without +side effects. Engines compute state transitions, validate invariants, +and provide utility functions that sub-updaters compose. + +=== Boundary + +* *Imports*: `+Model+` types (read-only) +* *Used by*: `+src/update/+` sub-updaters, `+src/components/+` views +* *Does NOT import*: `+Msg+`, `+RuntimeBridge+`, or any command modules + +=== Key Engines + +[width="100%",cols="48%,52%",options="header",] +|=== +|Engine |Purpose +|`+AntiCrash.res+` |Circuit breaker — validates neural tokens before +acceptance + +|`+OrbitalSync.res+` |Cross-panel synchronisation metrics + +|`+BurbleEngine.res+` |Pure voice huddle state transitions + +|`+ConnectionManager.res+` |Service health status transitions + +|`+ErrorBoundary.res+` |Standardized error handling for Gossamer +commands (v0.2.0) + +|`+RuntimeBridge.res+` |IPC bridge to Gossamer backend +|=== + +=== Invariants + +* Engines are pure functions — no promises, no side effects, no mutable +state +* Exception: `+RuntimeBridge.res+` and `+ErrorBoundary.res+` which +bridge to IPC +* Engine output is always a new state value, never a mutation + +=== Naming Convention + +`+{Domain}Engine.res+` or `+{Concept}.res+` — e.g. `+BurbleEngine.res+`, +`+ConnectionManager.res+` diff --git a/src/core/README.md b/src/core/README.md deleted file mode 100644 index f4c44048..00000000 --- a/src/core/README.md +++ /dev/null @@ -1,32 +0,0 @@ -# src/core/ — Domain Engines - -## Purpose - -Contains pure business logic engines that operate on model state without side effects. Engines compute state transitions, validate invariants, and provide utility functions that sub-updaters compose. - -## Boundary - -- **Imports**: `Model` types (read-only) -- **Used by**: `src/update/` sub-updaters, `src/components/` views -- **Does NOT import**: `Msg`, `RuntimeBridge`, or any command modules - -## Key Engines - -| Engine | Purpose | -|--------|---------| -| `AntiCrash.res` | Circuit breaker — validates neural tokens before acceptance | -| `OrbitalSync.res` | Cross-panel synchronisation metrics | -| `BurbleEngine.res` | Pure voice huddle state transitions | -| `ConnectionManager.res` | Service health status transitions | -| `ErrorBoundary.res` | Standardized error handling for Gossamer commands (v0.2.0) | -| `RuntimeBridge.res` | IPC bridge to Gossamer backend | - -## Invariants - -- Engines are pure functions — no promises, no side effects, no mutable state -- Exception: `RuntimeBridge.res` and `ErrorBoundary.res` which bridge to IPC -- Engine output is always a new state value, never a mutation - -## Naming Convention - -`{Domain}Engine.res` or `{Concept}.res` — e.g. `BurbleEngine.res`, `ConnectionManager.res` diff --git a/src/generated/README.adoc b/src/generated/README.adoc new file mode 100644 index 00000000..5bf45d08 --- /dev/null +++ b/src/generated/README.adoc @@ -0,0 +1,22 @@ +== src/generated/ — Auto-Generated Modules + +SPDX-License-Identifier: CC-BY-SA-4.0 + +*DO NOT EDIT FILES IN THIS DIRECTORY MANUALLY.* + +These modules are generated from ABI schemas and will be overwritten by +the generation tooling. + +=== Files + +* *CartridgeAbi.res* — Typed cartridge and tool definitions generated +from `+src/abi/cartridge-schema.json+`. Provides compile-time safety for +BoJ cartridge invocations — any typo in cartridge or tool name becomes a +compiler error. + +=== Regeneration + +[source,bash] +---- +deno task gen:cartridge-abi +---- diff --git a/src/generated/README.md b/src/generated/README.md deleted file mode 100644 index 8a4636f3..00000000 --- a/src/generated/README.md +++ /dev/null @@ -1,21 +0,0 @@ -# src/generated/ — Auto-Generated Modules - -SPDX-License-Identifier: CC-BY-SA-4.0 - -**DO NOT EDIT FILES IN THIS DIRECTORY MANUALLY.** - -These modules are generated from ABI schemas and will be overwritten by the -generation tooling. - -## Files - -- **CartridgeAbi.res** — Typed cartridge and tool definitions generated from - `src/abi/cartridge-schema.json`. Provides compile-time safety for BoJ - cartridge invocations — any typo in cartridge or tool name becomes a - compiler error. - -## Regeneration - -```bash -deno task gen:cartridge-abi -``` diff --git a/src/model/README.adoc b/src/model/README.adoc new file mode 100644 index 00000000..1071dc6f --- /dev/null +++ b/src/model/README.adoc @@ -0,0 +1,38 @@ +== src/model/ — Domain Type Modules + +=== Purpose + +Contains all domain-specific type definitions for PanLL’s TEA +architecture. Each model module defines the types (records, variants, +aliases) for one domain slice. The composition root `+Model.res+` +re-exports all types via `+include+`. + +=== Boundary + +* *Imports*: Nothing (leaf modules, no dependencies on other PanLL code) +* *Exported by*: `+Model.res+` via `+include XxxModel+` +* *Used by*: `+src/msg/+`, `+src/update/+`, `+src/core/+`, +`+src/commands/+`, `+src/components/+` + +=== Invariants + +* Model modules are pure type definitions — no functions, no side +effects +* All variant types must be exhaustively matched throughout the codebase +* New fields added to the `+model+` record in `+Model.res+` must have +init values in `+init()+` + +=== Naming Convention + +`+{Domain}Model.res+` — e.g. `+BurbleModel.res+`, `+ServiceModel.res+`, +`+VeriSimModel.res+` + +=== Adding a New Module + +[arabic] +. Create `+src/model/NewDomainModel.res+` with types +. Add `+include NewDomainModel+` to `+src/Model.res+` +. Add any new fields to the `+model+` record in `+Model.res+` +. Add init values in the `+init()+` function in `+Model.res+` +. Run `+deno task res:build+` — compiler errors show every place needing +updates diff --git a/src/model/README.md b/src/model/README.md deleted file mode 100644 index 56c537eb..00000000 --- a/src/model/README.md +++ /dev/null @@ -1,29 +0,0 @@ -# src/model/ — Domain Type Modules - -## Purpose - -Contains all domain-specific type definitions for PanLL's TEA architecture. Each model module defines the types (records, variants, aliases) for one domain slice. The composition root `Model.res` re-exports all types via `include`. - -## Boundary - -- **Imports**: Nothing (leaf modules, no dependencies on other PanLL code) -- **Exported by**: `Model.res` via `include XxxModel` -- **Used by**: `src/msg/`, `src/update/`, `src/core/`, `src/commands/`, `src/components/` - -## Invariants - -- Model modules are pure type definitions — no functions, no side effects -- All variant types must be exhaustively matched throughout the codebase -- New fields added to the `model` record in `Model.res` must have init values in `init()` - -## Naming Convention - -`{Domain}Model.res` — e.g. `BurbleModel.res`, `ServiceModel.res`, `VeriSimModel.res` - -## Adding a New Module - -1. Create `src/model/NewDomainModel.res` with types -2. Add `include NewDomainModel` to `src/Model.res` -3. Add any new fields to the `model` record in `Model.res` -4. Add init values in the `init()` function in `Model.res` -5. Run `deno task res:build` — compiler errors show every place needing updates diff --git a/src/msg/README.adoc b/src/msg/README.adoc new file mode 100644 index 00000000..e272b697 --- /dev/null +++ b/src/msg/README.adoc @@ -0,0 +1,38 @@ +== src/msg/ — TEA Message Modules + +=== Purpose + +Contains all message type definitions for PanLL’s TEA update loop. Each +module defines the message variants for one domain. The composition root +`+Msg.res+` re-exports all types via `+include+` and defines the unified +`+type msg+`. + +=== Boundary + +* *Imports*: `+Model+` (for types referenced in message payloads) +* *Exported by*: `+Msg.res+` via `+include XxxMsg+` +* *Used by*: `+src/update/+`, `+src/commands/+`, `+src/components/+` + +=== Invariants + +* Message modules define `+type xxxMsg+` variants only — no functions +* Every variant must have a handler in the corresponding +`+UpdateXxx.res+` +* Adding a variant to `+type msg+` in `+Msg.res+` requires a dispatch +case in `+Update.res+` + +=== Naming Convention + +`+{Domain}Msg.res+` — e.g. `+ServiceMsg.res+`, `+IdentityMsg.res+`, +`+BurbleMsg.res+` + +=== Adding a New Module + +[arabic] +. Create `+src/msg/NewDomainMsg.res+` with `+type newDomainMsg = ...+` +. Add `+include NewDomainMsg+` to `+src/Msg.res+` +. Add `+| NewDomain(newDomainMsg)+` to the unified `+type msg+` in +`+Msg.res+` +. Create the corresponding updater in `+src/update/UpdateNewDomain.res+` +. Add dispatch in `+src/Update.res+`: +`+| NewDomain(subMsg) => UpdateNewDomain.update(model, subMsg)+` diff --git a/src/msg/README.md b/src/msg/README.md deleted file mode 100644 index 6a7602af..00000000 --- a/src/msg/README.md +++ /dev/null @@ -1,29 +0,0 @@ -# src/msg/ — TEA Message Modules - -## Purpose - -Contains all message type definitions for PanLL's TEA update loop. Each module defines the message variants for one domain. The composition root `Msg.res` re-exports all types via `include` and defines the unified `type msg`. - -## Boundary - -- **Imports**: `Model` (for types referenced in message payloads) -- **Exported by**: `Msg.res` via `include XxxMsg` -- **Used by**: `src/update/`, `src/commands/`, `src/components/` - -## Invariants - -- Message modules define `type xxxMsg` variants only — no functions -- Every variant must have a handler in the corresponding `UpdateXxx.res` -- Adding a variant to `type msg` in `Msg.res` requires a dispatch case in `Update.res` - -## Naming Convention - -`{Domain}Msg.res` — e.g. `ServiceMsg.res`, `IdentityMsg.res`, `BurbleMsg.res` - -## Adding a New Module - -1. Create `src/msg/NewDomainMsg.res` with `type newDomainMsg = ...` -2. Add `include NewDomainMsg` to `src/Msg.res` -3. Add `| NewDomain(newDomainMsg)` to the unified `type msg` in `Msg.res` -4. Create the corresponding updater in `src/update/UpdateNewDomain.res` -5. Add dispatch in `src/Update.res`: `| NewDomain(subMsg) => UpdateNewDomain.update(model, subMsg)` diff --git a/src/panels/README.adoc b/src/panels/README.adoc new file mode 100644 index 00000000..a0b32fb8 --- /dev/null +++ b/src/panels/README.adoc @@ -0,0 +1,13 @@ +== src/panels/ — Panel Composition Root Views + +=== Purpose + +Contains the top-level panel composition views that arrange components +into the three-panel layout (Panel-L Symbolic, Panel-N Neural, Panel-W +World). Panel registry and lifecycle management. + +=== Boundary + +* *Imports*: `+Model+`, `+Msg+`, `+src/components/+` panel views +* *Used by*: `+View.res+` +* *Dependency direction*: panels → components → Tea_Html diff --git a/src/panels/README.md b/src/panels/README.md deleted file mode 100644 index b0c819bf..00000000 --- a/src/panels/README.md +++ /dev/null @@ -1,11 +0,0 @@ -# src/panels/ — Panel Composition Root Views - -## Purpose - -Contains the top-level panel composition views that arrange components into the three-panel layout (Panel-L Symbolic, Panel-N Neural, Panel-W World). Panel registry and lifecycle management. - -## Boundary - -- **Imports**: `Model`, `Msg`, `src/components/` panel views -- **Used by**: `View.res` -- **Dependency direction**: panels → components → Tea_Html diff --git a/src/tea/README.adoc b/src/tea/README.adoc new file mode 100644 index 00000000..bc27fb67 --- /dev/null +++ b/src/tea/README.adoc @@ -0,0 +1,39 @@ +== src/tea/ — Custom TEA Runtime + +=== Purpose + +PanLL’s permanent custom implementation of The Elm Architecture (TEA) +for ReScript. This is NOT rescript-tea — it’s a purpose-built runtime +with 18 modules supporting keyed diffing, fragments, SVG, 80+ +attributes, 30+ events, HTTP, JSON, keyboard, mouse, window, SSR, debug, +and testing. + +=== Boundary + +* *Imports*: Nothing (standalone runtime, no PanLL dependencies) +* *Used by*: Everything — all panels, all views, all subscriptions +* *Never replaced by*: rescript-tea@0.16.0 (incompatible API) + +=== Invariants + +* This is a permanent fork, NOT a temporary shim +* `+list{}+` syntax for vdom children: +`+Tea_Html.div(list{}, list{...})+` +* `+Events.onClick+` / `+Events.onInput+` for events (NOT +`+Events.onCheck+`) +* `+Attrs.style("property", "value")+` takes two string args +* `+Tea_Cmd.call(callbacks => ...)+` for async commands + +=== Key Modules + +[cols=",",options="header",] +|=== +|Module |Purpose +|`+Tea_App.res+` |Application bootstrap (`+standardProgram+`) +|`+Tea_Html.res+` |Virtual DOM elements and attributes +|`+Tea_Cmd.res+` |Side-effect commands +|`+Tea_Sub.res+` |Subscriptions (timers, events) +|`+Tea_Json.res+` |JSON decoders for TEA +|`+Tea_Http.res+` |HTTP request commands +|`+Tea_Test.res+` |Testing utilities +|=== diff --git a/src/tea/README.md b/src/tea/README.md deleted file mode 100644 index f55ba754..00000000 --- a/src/tea/README.md +++ /dev/null @@ -1,31 +0,0 @@ -# src/tea/ — Custom TEA Runtime - -## Purpose - -PanLL's permanent custom implementation of The Elm Architecture (TEA) for ReScript. This is NOT rescript-tea — it's a purpose-built runtime with 18 modules supporting keyed diffing, fragments, SVG, 80+ attributes, 30+ events, HTTP, JSON, keyboard, mouse, window, SSR, debug, and testing. - -## Boundary - -- **Imports**: Nothing (standalone runtime, no PanLL dependencies) -- **Used by**: Everything — all panels, all views, all subscriptions -- **Never replaced by**: rescript-tea@0.16.0 (incompatible API) - -## Invariants - -- This is a permanent fork, NOT a temporary shim -- `list{}` syntax for vdom children: `Tea_Html.div(list{}, list{...})` -- `Events.onClick` / `Events.onInput` for events (NOT `Events.onCheck`) -- `Attrs.style("property", "value")` takes two string args -- `Tea_Cmd.call(callbacks => ...)` for async commands - -## Key Modules - -| Module | Purpose | -|--------|---------| -| `Tea_App.res` | Application bootstrap (`standardProgram`) | -| `Tea_Html.res` | Virtual DOM elements and attributes | -| `Tea_Cmd.res` | Side-effect commands | -| `Tea_Sub.res` | Subscriptions (timers, events) | -| `Tea_Json.res` | JSON decoders for TEA | -| `Tea_Http.res` | HTTP request commands | -| `Tea_Test.res` | Testing utilities | diff --git a/src/update/README.adoc b/src/update/README.adoc new file mode 100644 index 00000000..1fec35e5 --- /dev/null +++ b/src/update/README.adoc @@ -0,0 +1,39 @@ +== src/update/ — TEA Sub-Updaters + +=== Purpose + +Contains pure state transition functions for each domain. The main +`+Update.res+` dispatcher routes messages to the appropriate +sub-updater. Each sub-updater returns `+(model, Tea_Cmd.t)+`. + +=== Boundary + +* *Imports*: `+Model+`, `+Msg+`, domain-specific `+XxxCmd+` modules +* *Used by*: `+Update.res+` (the only consumer) +* *Dependency direction*: update → commands → RuntimeBridge + +=== Invariants + +* Sub-updaters are pure: +`+(model, domainMsg) => (model, Tea_Cmd.t)+` +* Side effects are encoded as `+Tea_Cmd.t+` values, never executed +directly +* The only imperative call in the update layer is `+Storage.save()+` in +`+SaveState+` + +=== Naming Convention + +`+Update{Domain}.res+` — e.g. `+UpdateService.res+`, +`+UpdateSettings.res+`, `+UpdateAerie.res+` + +=== Adding a New Sub-Updater + +[arabic] +. Create `+src/update/UpdateNewDomain.res+` with +`+let updateNewDomain = (model, subMsg) => ...+` +. Open `+Model+` and `+Msg+` at the top +. Handle every variant of `+newDomainMsg+` exhaustively +. Add dispatch in `+src/Update.res+`: +`+| NewDomain(subMsg) => UpdateNewDomain.updateNewDomain(model, subMsg)+` +. Consider adding to `+shouldAutoSave+` exclusion if the domain has its +own persistence diff --git a/src/update/README.md b/src/update/README.md deleted file mode 100644 index 81861192..00000000 --- a/src/update/README.md +++ /dev/null @@ -1,29 +0,0 @@ -# src/update/ — TEA Sub-Updaters - -## Purpose - -Contains pure state transition functions for each domain. The main `Update.res` dispatcher routes messages to the appropriate sub-updater. Each sub-updater returns `(model, Tea_Cmd.t)`. - -## Boundary - -- **Imports**: `Model`, `Msg`, domain-specific `XxxCmd` modules -- **Used by**: `Update.res` (the only consumer) -- **Dependency direction**: update → commands → RuntimeBridge - -## Invariants - -- Sub-updaters are pure: `(model, domainMsg) => (model, Tea_Cmd.t)` -- Side effects are encoded as `Tea_Cmd.t` values, never executed directly -- The only imperative call in the update layer is `Storage.save()` in `SaveState` - -## Naming Convention - -`Update{Domain}.res` — e.g. `UpdateService.res`, `UpdateSettings.res`, `UpdateAerie.res` - -## Adding a New Sub-Updater - -1. Create `src/update/UpdateNewDomain.res` with `let updateNewDomain = (model, subMsg) => ...` -2. Open `Model` and `Msg` at the top -3. Handle every variant of `newDomainMsg` exhaustively -4. Add dispatch in `src/Update.res`: `| NewDomain(subMsg) => UpdateNewDomain.updateNewDomain(model, subMsg)` -5. Consider adding to `shouldAutoSave` exclusion if the domain has its own persistence diff --git a/tools/invariant-path/README.adoc b/tools/invariant-path/README.adoc new file mode 100644 index 00000000..1f9f873e --- /dev/null +++ b/tools/invariant-path/README.adoc @@ -0,0 +1,26 @@ +== Invariant Path Integration (PanLL) + +PanLL wrapper script: + +[source,bash] +---- +./scripts/invariant-path.sh scan --file ./README.adoc --artifact-uri repo://README.adoc --write +---- + +Via `+just+` from repo root: + +[source,bash] +---- +just invariant-path scan --file ./README.adoc --artifact-uri repo://README.adoc --write +---- + +Default profile: `+panll+` + +Focus: - model -> reality - benchmark -> capability - descriptive -> +normative + +Store path defaults to `+.invariant-path/+` in the current working +directory. + +Desktop/start-menu launcher for shared tooling: - +`+/var/mnt/eclipse/repos/.desktop-tools/invariant-path-launcher.sh+` diff --git a/tools/invariant-path/README.md b/tools/invariant-path/README.md deleted file mode 100644 index f888cf78..00000000 --- a/tools/invariant-path/README.md +++ /dev/null @@ -1,25 +0,0 @@ -# Invariant Path Integration (PanLL) - -PanLL wrapper script: - -```bash -./scripts/invariant-path.sh scan --file ./README.adoc --artifact-uri repo://README.adoc --write -``` - -Via `just` from repo root: - -```bash -just invariant-path scan --file ./README.adoc --artifact-uri repo://README.adoc --write -``` - -Default profile: `panll` - -Focus: -- model -> reality -- benchmark -> capability -- descriptive -> normative - -Store path defaults to `.invariant-path/` in the current working directory. - -Desktop/start-menu launcher for shared tooling: -- `/var/mnt/eclipse/repos/.desktop-tools/invariant-path-launcher.sh` diff --git a/tutorials/identity-management-video-script.adoc b/tutorials/identity-management-video-script.adoc new file mode 100644 index 00000000..923032e5 --- /dev/null +++ b/tutorials/identity-management-video-script.adoc @@ -0,0 +1,458 @@ +== PanLL Identity Management Tutorial Video Script + +=== Video Title + +*"`PanLL v0.2.0: Mastering Identity Management - Capture, Share, and +Restore Your Workbench`"* + +=== Video Duration + +*12-15 minutes* + +=== Target Audience + +* PanLL users upgrading from v0.1.x +* New users exploring v0.2.0 features +* Team leads managing collaborative workbenches +* Developers interested in extending identity management + +=== Video Outline + +==== 1. Introduction (0:00 - 1:30) + +*Visual*: Screen recording of PanLL interface with animated callouts + +*Narration*: + +.... +"Welcome to this comprehensive tutorial on PanLL v0.2.0's Identity Management system. +In this video, we'll explore how to capture your complete workbench configuration, +share it with your team, and restore it whenever needed. + +By the end of this tutorial, you'll be able to: +- Create and manage identity snapshots +- Share configurations with your team via Burble +- Restore previous setups with one click +- Automate your workflow with identity management + +Let's get started!" +.... + +*On-screen text*: - "`PanLL v0.2.0 Identity Management`" - "`Capture. +Share. Restore.`" - "`Your workbench, preserved`" + +==== 2. Understanding Identity Snapshots (1:30 - 4:00) + +*Visual*: Diagram showing snapshot components with animations + +*Narration*: + +.... +"First, let's understand what an identity snapshot is. + +An identity snapshot in PanLL captures your complete workbench configuration: + +1. **Panel State**: The positions, sizes, and visibility of all your panels +2. **Settings**: All your configuration preferences and customizations +3. **Service URLs**: Your registered service endpoints and connections +4. **Metadata**: Additional information like tags and timestamps + +Think of it as a photograph of your entire workspace that you can restore later, +or share with teammates to ensure everyone has the same setup. + +This is especially useful for: +- Onboarding new team members +- Switching between different projects +- Recovering from configuration errors +- Standardizing setups across your organization" +.... + +*Demo*: 1. Show current panel layout 2. Show settings configuration 3. +Show service registry 4. Explain how all these are captured in a +snapshot + +==== 3. Creating Your First Snapshot (4:00 - 7:30) + +*Visual*: Screen recording of snapshot creation process + +*Narration*: + +.... +"Now let's create our first identity snapshot. +There are several ways to do this in PanLL v0.2.0. + +**Method 1: Using the System Tray** + +The easiest way is through the system tray icon: +1. Right-click the PanLL icon in your system tray +2. Hover over 'Identity Management' +3. Click 'Save Current Identity' +4. Enter a descriptive name like 'Project Alpha Setup' +5. Click Save + +**Method 2: Using the Command Palette** + +You can also use the command palette: +1. Press Ctrl+K or Cmd+K to open the command palette +2. Type 'identity save' and select the command +3. Fill in the details and save + +**Method 3: Using the CLI** + +For automation, use the command line: +```bash +panll identity save --name "My Setup" --description "Main project configuration" +.... + +Let me demonstrate all three methods so you can choose what works best +for you.” + +.... + +**Demo**: +1. Show system tray method (slow, with annotations) +2. Show command palette method (normal speed) +3. Show CLI method in terminal +4. Verify snapshot was created in the identity manager + +**Pro Tip**: +.... + +"`Notice how each snapshot gets a unique ID and timestamp. This makes it +easy to manage multiple configurations and track when they were +created.`" + +.... + +### 4. Managing Snapshots (7:30 - 10:00) + +**Visual**: Identity manager interface walkthrough + +**Narration**: +.... + +“Now that we’ve created a snapshot, let’s explore how to manage it. + +*Viewing Snapshots*: 1. Open the Identity Manager from the system tray +or main menu 2. Here you’ll see all your saved snapshots with their +names and creation dates 3. Click on any snapshot to see its details + +*Renaming and Updating*: 1. Select a snapshot 2. Click the edit button +3. Update the name or description 4. Save your changes + +*Deleting Snapshots*: 1. Select the snapshot you want to remove 2. Click +the delete button 3. Confirm the deletion + +*Best Practices for Snapshot Management*: - Use descriptive names like +'`Project X - UI Research Phase`' - Include dates for time-sensitive +configurations - Regularly clean up old snapshots you no longer need - +Consider using tags to categorize related snapshots + +Let me show you how to perform these management tasks.” + +.... + +**Demo**: +1. Open Identity Manager +2. Show list of snapshots +3. Rename a snapshot +4. Delete a snapshot +5. Show snapshot details + +### 5. Team Broadcasting (10:00 - 13:00) + +**Visual**: Team broadcasting workflow with multiple team members + +**Narration**: +.... + +“One of the most powerful features in v0.2.0 is team broadcasting. This +allows you to share your identity snapshots with your entire team +instantly. + +*How Team Broadcasting Works*: 1. Save your current identity as a +snapshot 2. Open the system tray menu 3. Hover over '`Team`' 4. Click +'`Broadcast Current Identity`' 5. Select the snapshot you want to share +6. Add an optional message for your team 7. Click Broadcast + +Your team members will receive a notification and can choose to apply +the snapshot to their own workbench. + +*Use Cases for Team Broadcasting*: - Onboarding new team members with +standardized setups - Sharing project-specific configurations - +Distributing updates to service endpoints - Synchronizing team workflows + +*Security Considerations*: - Only broadcast to trusted team members - +Review snapshot contents before sharing - Be cautious with sensitive +configuration data - Use Burble’s access controls to limit who can +receive broadcasts + +Let me demonstrate the broadcasting process and show what it looks like +from the receiver’s perspective.” + +.... + +**Demo**: +1. Create a test snapshot +2. Broadcast it to the team +3. Show receiver's notification +4. Show how to apply the broadcasted snapshot +5. Show broadcast history + +### 6. Advanced Features (13:00 - 16:00) + +**Visual**: Advanced features with code examples + +**Narration**: +.... + +“Now that you’ve mastered the basics, let’s explore some advanced +features. + +*Automatic Snapshots*: You can configure PanLL to automatically save +snapshots: - On a schedule (e.g., every hour) - When closing the +application - When specific events occur + +*Snapshot Diffing*: Compare two snapshots to see what’s changed: + +[source,bash] +---- +panll identity diff +---- + +*Batch Operations*: Perform operations on multiple snapshots: + +[source,bash] +---- +# Export all snapshots +panll identity export --all + +# Delete snapshots older than 30 days +panll identity cleanup --older-than 30d +---- + +*Programmatic Access*: Access identity functions from your own scripts: + +[source,javascript] +---- +// Save current state +const snapshot = await invoke("identity_save", { + name: "Programmatic Snapshot", + panll_state: JSON.stringify(storage.serialize()), + settings: JSON.stringify(await settings_get()), + service_urls: JSON.stringify(await service_registry_get()) +}); + +// Load a snapshot +const loaded = await invoke("identity_load", { id: snapshot.id }); +---- + +*Custom Storage Backends*: Extend PanLL with your own storage solutions: +- S3-compatible storage - PostgreSQL database - Custom enterprise +solutions + +These advanced features give you even more control over your identity +management workflow.” + +.... + +**Demo**: +1. Show automatic snapshot configuration +2. Demonstrate snapshot diffing +3. Show batch export/import +4. Show simple programmatic example + +### 7. Troubleshooting (16:00 - 18:00) + +**Visual**: Common issues and solutions + +**Narration**: +.... + +“Let’s cover some common issues and how to resolve them. + +*Issue 1: Snapshots not appearing* - Check VeriSimDB connection - Verify +filesystem permissions - Review PanLL logs: journalctl -u panll + +*Issue 2: Broadcast failures* - Check Burble service status - Verify +network connectivity - Test with smaller snapshots first + +*Issue 3: Performance issues* - Check cache configuration - Monitor +resource usage with htop - Review snapshot sizes + +*Issue 4: Permission errors* - Verify directory permissions: ls -la +/var/panll - Check user ownership: sudo chown -R panll:panll /var/panll +- Review SELinux settings if applicable + +For more troubleshooting tips, check out our comprehensive guide at +panll.hyperpolymath.dev/docs/troubleshooting.” + +.... + +**Demo**: +1. Simulate a connection issue +2. Show how to diagnose +3. Demonstrate resolution +4. Show log inspection + +### 8. Best Practices (18:00 - 20:00) + +**Visual**: Best practices checklist + +**Narration**: +.... + +“To wrap up, let’s review some best practices for identity management: + +*Naming Conventions*: - Be descriptive: "`Project X - UI Research`" not +"`Snapshot 1`" - Include dates for time-sensitive configurations - Use +consistent naming schemes across your team + +*Regular Maintenance*: - Clean up old snapshots monthly - Verify backup +integrity - Test restore procedures + +*Team Workflows*: - Broadcast team configurations at project start - +Share specialized setups for specific tasks - Use snapshots for +onboarding new members + +*Security*: - Review snapshot contents before sharing - Use VeriSimDB +access controls - Be cautious with sensitive data + +*Performance*: - Keep snapshots under 10MB when possible - Use +compression for large configurations - Monitor cache hit rates + +By following these best practices, you’ll get the most out of PanLL’s +identity management system.” + +.... + +**Demo**: +1. Show well-organized snapshot list +2. Demonstrate good naming +3. Show cleanup process +4. Show team workflow + +### 9. Conclusion & Next Steps (20:00 - 22:00) + +**Visual**: Summary with call-to-action + +**Narration**: +.... + +“Congratulations! You’ve now mastered PanLL’s identity management +system. + +*What We’ve Covered*: ✅ Understanding identity snapshots ✅ Creating +and managing snapshots ✅ Team broadcasting and collaboration ✅ +Advanced features and automation ✅ Troubleshooting and best practices + +*Next Steps*: 1. Start using identity snapshots in your daily workflow +2. Explore team broadcasting with your colleagues 3. Automate repetitive +configurations 4. Check out our developer guide to extend the system + +*Resources*: - Documentation: panll.hyperpolymath.dev/docs - Community: +github.com/hyperpolymath/panll/discussions - Support: +support@hyperpolymath.dev + +*Upcoming Workshop*: Join our community workshop on June 5th where we’ll +dive even deeper into identity management and show you advanced +techniques. Register at: panll.hyperpolymath.dev/workshop + +Thank you for watching! If you found this tutorial helpful, please like +and subscribe. Leave your questions in the comments below, and we’ll be +happy to help. + +Happy paneling!” + +.... + +**On-screen text**: +- "You're now a PanLL Identity Management expert!" +- "Questions? Ask in the comments" +- "Subscribe for more tutorials" +- "panll.hyperpolymath.dev/workshop - June 5th" + +### 10. Outro (22:00 - 22:30) + +**Visual**: End screen with social links and call-to-action + +**Narration**: +.... + +“Don’t forget to: - Subscribe for more PanLL tutorials - Star us on +GitHub: github.com/hyperpolymath/panll - Join our community discussions +- Follow us on social media for updates + +See you in the next video where we’ll explore PanLL’s plugin system! + +Bye for now!” ``` + +*On-screen text*: - GitHub: github.com/hyperpolymath/panll - Docs: +panll.hyperpolymath.dev/docs - Community: +github.com/hyperpolymath/panll/discussions - Workshop: +panll.hyperpolymath.dev/workshop + +=== Production Notes + +==== Equipment + +* Screen recording: OBS Studio +* Microphone: Blue Yeti or equivalent +* Camera: 1080p webcam +* Editing: Kdenlive or Adobe Premiere + +==== Style Guide + +* *Font*: Fira Code for code, Inter for text +* *Colors*: PanLL brand colors (#4F46E5, #10B981, #F59E0B) +* *Transitions*: Clean cuts, no fancy transitions +* *Pacing*: 120-150 words per minute +* *Tone*: Friendly, professional, enthusiastic + +==== Post-Production + +[arabic] +. Add captions for accessibility +. Create chapters for easy navigation +. Add end screen with subscription prompt +. Optimize for YouTube (1080p, 30fps) +. Create thumbnail with title and key visuals + +==== Thumbnail Ideas + +[arabic] +. PanLL interface with "`Identity Management`" overlay +. Before/after comparison of workbench states +. Team collaboration visual with broadcasting concept +. Snapshot icon with "`New in v0.2.0`" badge + +=== Script Variations + +==== Short Version (5-7 minutes) + +Focus on: - What are identity snapshots? (1 min) - Creating and loading +snapshots (2 min) - Team broadcasting basics (2 min) - Quick demo and +wrap-up + +==== Developer Version (15-20 minutes) + +Add sections on: - Extending identity management - Custom storage +backends - Programmatic access - Plugin development + +==== Team Version (10-12 minutes) + +Focus on: - Team broadcasting workflows - Onboarding new members - +Standardizing configurations - Collaboration best practices + +=== Additional Resources + +* Blog post: https://panll.hyperpolymath.dev/blog/v0.2.0-release[v0.2.0 +Release Announcement] +* Documentation: +https://panll.hyperpolymath.dev/docs/identity-user-guide[Identity User +Guide] +* API Reference: +https://panll.hyperpolymath.dev/docs/api-reference[Identity Management +API] +* Migration Guide: +https://panll.hyperpolymath.dev/docs/migration[Upgrading from v0.1.x] diff --git a/tutorials/identity-management-video-script.md b/tutorials/identity-management-video-script.md deleted file mode 100644 index 5e5e651d..00000000 --- a/tutorials/identity-management-video-script.md +++ /dev/null @@ -1,462 +0,0 @@ -# PanLL Identity Management Tutorial Video Script - -## Video Title -**"PanLL v0.2.0: Mastering Identity Management - Capture, Share, and Restore Your Workbench"** - -## Video Duration -**12-15 minutes** - -## Target Audience -- PanLL users upgrading from v0.1.x -- New users exploring v0.2.0 features -- Team leads managing collaborative workbenches -- Developers interested in extending identity management - -## Video Outline - -### 1. Introduction (0:00 - 1:30) - -**Visual**: Screen recording of PanLL interface with animated callouts - -**Narration**: -``` -"Welcome to this comprehensive tutorial on PanLL v0.2.0's Identity Management system. -In this video, we'll explore how to capture your complete workbench configuration, -share it with your team, and restore it whenever needed. - -By the end of this tutorial, you'll be able to: -- Create and manage identity snapshots -- Share configurations with your team via Burble -- Restore previous setups with one click -- Automate your workflow with identity management - -Let's get started!" -``` - -**On-screen text**: -- "PanLL v0.2.0 Identity Management" -- "Capture. Share. Restore." -- "Your workbench, preserved" - -### 2. Understanding Identity Snapshots (1:30 - 4:00) - -**Visual**: Diagram showing snapshot components with animations - -**Narration**: -``` -"First, let's understand what an identity snapshot is. - -An identity snapshot in PanLL captures your complete workbench configuration: - -1. **Panel State**: The positions, sizes, and visibility of all your panels -2. **Settings**: All your configuration preferences and customizations -3. **Service URLs**: Your registered service endpoints and connections -4. **Metadata**: Additional information like tags and timestamps - -Think of it as a photograph of your entire workspace that you can restore later, -or share with teammates to ensure everyone has the same setup. - -This is especially useful for: -- Onboarding new team members -- Switching between different projects -- Recovering from configuration errors -- Standardizing setups across your organization" -``` - -**Demo**: -1. Show current panel layout -2. Show settings configuration -3. Show service registry -4. Explain how all these are captured in a snapshot - -### 3. Creating Your First Snapshot (4:00 - 7:30) - -**Visual**: Screen recording of snapshot creation process - -**Narration**: -``` -"Now let's create our first identity snapshot. -There are several ways to do this in PanLL v0.2.0. - -**Method 1: Using the System Tray** - -The easiest way is through the system tray icon: -1. Right-click the PanLL icon in your system tray -2. Hover over 'Identity Management' -3. Click 'Save Current Identity' -4. Enter a descriptive name like 'Project Alpha Setup' -5. Click Save - -**Method 2: Using the Command Palette** - -You can also use the command palette: -1. Press Ctrl+K or Cmd+K to open the command palette -2. Type 'identity save' and select the command -3. Fill in the details and save - -**Method 3: Using the CLI** - -For automation, use the command line: -```bash -panll identity save --name "My Setup" --description "Main project configuration" -``` - -Let me demonstrate all three methods so you can choose what works best for you." -``` - -**Demo**: -1. Show system tray method (slow, with annotations) -2. Show command palette method (normal speed) -3. Show CLI method in terminal -4. Verify snapshot was created in the identity manager - -**Pro Tip**: -``` -"Notice how each snapshot gets a unique ID and timestamp. -This makes it easy to manage multiple configurations and track when they were created." -``` - -### 4. Managing Snapshots (7:30 - 10:00) - -**Visual**: Identity manager interface walkthrough - -**Narration**: -``` -"Now that we've created a snapshot, let's explore how to manage it. - -**Viewing Snapshots**: -1. Open the Identity Manager from the system tray or main menu -2. Here you'll see all your saved snapshots with their names and creation dates -3. Click on any snapshot to see its details - -**Renaming and Updating**: -1. Select a snapshot -2. Click the edit button -3. Update the name or description -4. Save your changes - -**Deleting Snapshots**: -1. Select the snapshot you want to remove -2. Click the delete button -3. Confirm the deletion - -**Best Practices for Snapshot Management**: -- Use descriptive names like 'Project X - UI Research Phase' -- Include dates for time-sensitive configurations -- Regularly clean up old snapshots you no longer need -- Consider using tags to categorize related snapshots - -Let me show you how to perform these management tasks." -``` - -**Demo**: -1. Open Identity Manager -2. Show list of snapshots -3. Rename a snapshot -4. Delete a snapshot -5. Show snapshot details - -### 5. Team Broadcasting (10:00 - 13:00) - -**Visual**: Team broadcasting workflow with multiple team members - -**Narration**: -``` -"One of the most powerful features in v0.2.0 is team broadcasting. -This allows you to share your identity snapshots with your entire team instantly. - -**How Team Broadcasting Works**: -1. Save your current identity as a snapshot -2. Open the system tray menu -3. Hover over 'Team' -4. Click 'Broadcast Current Identity' -5. Select the snapshot you want to share -6. Add an optional message for your team -7. Click Broadcast - -Your team members will receive a notification and can choose to apply the snapshot to their own workbench. - -**Use Cases for Team Broadcasting**: -- Onboarding new team members with standardized setups -- Sharing project-specific configurations -- Distributing updates to service endpoints -- Synchronizing team workflows - -**Security Considerations**: -- Only broadcast to trusted team members -- Review snapshot contents before sharing -- Be cautious with sensitive configuration data -- Use Burble's access controls to limit who can receive broadcasts - -Let me demonstrate the broadcasting process and show what it looks like from the receiver's perspective." -``` - -**Demo**: -1. Create a test snapshot -2. Broadcast it to the team -3. Show receiver's notification -4. Show how to apply the broadcasted snapshot -5. Show broadcast history - -### 6. Advanced Features (13:00 - 16:00) - -**Visual**: Advanced features with code examples - -**Narration**: -``` -"Now that you've mastered the basics, let's explore some advanced features. - -**Automatic Snapshots**: -You can configure PanLL to automatically save snapshots: -- On a schedule (e.g., every hour) -- When closing the application -- When specific events occur - -**Snapshot Diffing**: -Compare two snapshots to see what's changed: -```bash -panll identity diff -``` - -**Batch Operations**: -Perform operations on multiple snapshots: -```bash -# Export all snapshots -panll identity export --all - -# Delete snapshots older than 30 days -panll identity cleanup --older-than 30d -``` - -**Programmatic Access**: -Access identity functions from your own scripts: -```javascript -// Save current state -const snapshot = await invoke("identity_save", { - name: "Programmatic Snapshot", - panll_state: JSON.stringify(storage.serialize()), - settings: JSON.stringify(await settings_get()), - service_urls: JSON.stringify(await service_registry_get()) -}); - -// Load a snapshot -const loaded = await invoke("identity_load", { id: snapshot.id }); -``` - -**Custom Storage Backends**: -Extend PanLL with your own storage solutions: -- S3-compatible storage -- PostgreSQL database -- Custom enterprise solutions - -These advanced features give you even more control over your identity management workflow." -``` - -**Demo**: -1. Show automatic snapshot configuration -2. Demonstrate snapshot diffing -3. Show batch export/import -4. Show simple programmatic example - -### 7. Troubleshooting (16:00 - 18:00) - -**Visual**: Common issues and solutions - -**Narration**: -``` -"Let's cover some common issues and how to resolve them. - -**Issue 1: Snapshots not appearing** -- Check VeriSimDB connection -- Verify filesystem permissions -- Review PanLL logs: journalctl -u panll - -**Issue 2: Broadcast failures** -- Check Burble service status -- Verify network connectivity -- Test with smaller snapshots first - -**Issue 3: Performance issues** -- Check cache configuration -- Monitor resource usage with htop -- Review snapshot sizes - -**Issue 4: Permission errors** -- Verify directory permissions: ls -la /var/panll -- Check user ownership: sudo chown -R panll:panll /var/panll -- Review SELinux settings if applicable - -For more troubleshooting tips, check out our comprehensive guide at panll.hyperpolymath.dev/docs/troubleshooting." -``` - -**Demo**: -1. Simulate a connection issue -2. Show how to diagnose -3. Demonstrate resolution -4. Show log inspection - -### 8. Best Practices (18:00 - 20:00) - -**Visual**: Best practices checklist - -**Narration**: -``` -"To wrap up, let's review some best practices for identity management: - -**Naming Conventions**: -- Be descriptive: "Project X - UI Research" not "Snapshot 1" -- Include dates for time-sensitive configurations -- Use consistent naming schemes across your team - -**Regular Maintenance**: -- Clean up old snapshots monthly -- Verify backup integrity -- Test restore procedures - -**Team Workflows**: -- Broadcast team configurations at project start -- Share specialized setups for specific tasks -- Use snapshots for onboarding new members - -**Security**: -- Review snapshot contents before sharing -- Use VeriSimDB access controls -- Be cautious with sensitive data - -**Performance**: -- Keep snapshots under 10MB when possible -- Use compression for large configurations -- Monitor cache hit rates - -By following these best practices, you'll get the most out of PanLL's identity management system." -``` - -**Demo**: -1. Show well-organized snapshot list -2. Demonstrate good naming -3. Show cleanup process -4. Show team workflow - -### 9. Conclusion & Next Steps (20:00 - 22:00) - -**Visual**: Summary with call-to-action - -**Narration**: -``` -"Congratulations! You've now mastered PanLL's identity management system. - -**What We've Covered**: -✅ Understanding identity snapshots -✅ Creating and managing snapshots -✅ Team broadcasting and collaboration -✅ Advanced features and automation -✅ Troubleshooting and best practices - -**Next Steps**: -1. Start using identity snapshots in your daily workflow -2. Explore team broadcasting with your colleagues -3. Automate repetitive configurations -4. Check out our developer guide to extend the system - -**Resources**: -- Documentation: panll.hyperpolymath.dev/docs -- Community: github.com/hyperpolymath/panll/discussions -- Support: support@hyperpolymath.dev - -**Upcoming Workshop**: -Join our community workshop on June 5th where we'll dive even deeper into -identity management and show you advanced techniques. -Register at: panll.hyperpolymath.dev/workshop - -Thank you for watching! If you found this tutorial helpful, please like and subscribe. -Leave your questions in the comments below, and we'll be happy to help. - -Happy paneling!" -``` - -**On-screen text**: -- "You're now a PanLL Identity Management expert!" -- "Questions? Ask in the comments" -- "Subscribe for more tutorials" -- "panll.hyperpolymath.dev/workshop - June 5th" - -### 10. Outro (22:00 - 22:30) - -**Visual**: End screen with social links and call-to-action - -**Narration**: -``` -"Don't forget to: -- Subscribe for more PanLL tutorials -- Star us on GitHub: github.com/hyperpolymath/panll -- Join our community discussions -- Follow us on social media for updates - -See you in the next video where we'll explore PanLL's plugin system! - -Bye for now!" -``` - -**On-screen text**: -- GitHub: github.com/hyperpolymath/panll -- Docs: panll.hyperpolymath.dev/docs -- Community: github.com/hyperpolymath/panll/discussions -- Workshop: panll.hyperpolymath.dev/workshop - -## Production Notes - -### Equipment -- Screen recording: OBS Studio -- Microphone: Blue Yeti or equivalent -- Camera: 1080p webcam -- Editing: Kdenlive or Adobe Premiere - -### Style Guide -- **Font**: Fira Code for code, Inter for text -- **Colors**: PanLL brand colors (#4F46E5, #10B981, #F59E0B) -- **Transitions**: Clean cuts, no fancy transitions -- **Pacing**: 120-150 words per minute -- **Tone**: Friendly, professional, enthusiastic - -### Post-Production -1. Add captions for accessibility -2. Create chapters for easy navigation -3. Add end screen with subscription prompt -4. Optimize for YouTube (1080p, 30fps) -5. Create thumbnail with title and key visuals - -### Thumbnail Ideas -1. PanLL interface with "Identity Management" overlay -2. Before/after comparison of workbench states -3. Team collaboration visual with broadcasting concept -4. Snapshot icon with "New in v0.2.0" badge - -## Script Variations - -### Short Version (5-7 minutes) -Focus on: -- What are identity snapshots? (1 min) -- Creating and loading snapshots (2 min) -- Team broadcasting basics (2 min) -- Quick demo and wrap-up - -### Developer Version (15-20 minutes) -Add sections on: -- Extending identity management -- Custom storage backends -- Programmatic access -- Plugin development - -### Team Version (10-12 minutes) -Focus on: -- Team broadcasting workflows -- Onboarding new members -- Standardizing configurations -- Collaboration best practices - -## Additional Resources - -- Blog post: [v0.2.0 Release Announcement](https://panll.hyperpolymath.dev/blog/v0.2.0-release) -- Documentation: [Identity User Guide](https://panll.hyperpolymath.dev/docs/identity-user-guide) -- API Reference: [Identity Management API](https://panll.hyperpolymath.dev/docs/api-reference) -- Migration Guide: [Upgrading from v0.1.x](https://panll.hyperpolymath.dev/docs/migration) \ No newline at end of file diff --git a/workshop/presentation/slides.adoc b/workshop/presentation/slides.adoc new file mode 100644 index 00000000..bffed8ce --- /dev/null +++ b/workshop/presentation/slides.adoc @@ -0,0 +1,159 @@ +== PanLL v0.2.0 Workshop: Advanced Identity Management & Team Collaboration + +=== Slide 1: Title Slide + +* *Title*: Mastering PanLL v0.2.0 +* *Subtitle*: Advanced Identity Management & Team Collaboration +* *Date*: June 5, 2024 +* *Speakers*: Jonathan, Claude, Vibe, Gemini + +=== Slide 2: Workshop Agenda + +[arabic] +. Welcome & Introduction (10 min) +. Identity Management Architecture (20 min) +. Advanced Team Collaboration (20 min) +. Automation & Integration (20 min) +. Extending PanLL (20 min) +. Q&A Session (20 min) +. Wrap-up & Next Steps (10 min) + +=== Slide 3: About PanLL v0.2.0 + +* *Connected Workbench* release +* Key features: +** System tray integration +** Burble/Gossamer service toggling +** Identity state capture with VeriSimDB +** Team replication capabilities + +=== Slide 4: Identity Management Architecture + +==== Storage Layer + +* VeriSimDB (primary) +* Filesystem fallback +* Cache optimization + +==== Performance + +* LRU caching +* Batch operations +* Compression techniques + +=== Slide 5: Identity Snapshot Structure + +[source,json] +---- +{ + "panels": [...], + "settings": {...}, + "service_urls": {...}, + "metadata": {...}, + "timestamp": "..." +} +---- + +=== Slide 6: Team Collaboration with Burble + +==== Architecture + +* Broadcast protocol +* Security model +* Conflict resolution + +==== Workflows + +* Team onboarding +* Project synchronization +* Access control patterns + +=== Slide 7: Automation Techniques + +==== CLI Power User Tips + +[source,bash] +---- +# Batch save all identities +panll identity save-all + +# Broadcast to team +panll team broadcast --all +---- + +==== Scripting Examples + +[source,javascript] +---- +// JavaScript API +const panll = require('panll-client'); +await panll.identity.save('work-config'); +---- + +=== Slide 8: Extending PanLL + +==== Plugin System + +* Architecture overview +* Plugin API +* Lifecycle hooks + +==== Custom Storage Backends + +[source,rust] +---- +// Example S3 backend +struct S3Backend; +impl StorageBackend for S3Backend { + fn save(&self, data: &[u8]) -> Result<()> { + // S3 implementation + } +} +---- + +=== Slide 9: Q&A Session + +* Open floor for questions +* Troubleshooting common issues +* Roadmap discussion +* Community contributions + +=== Slide 10: Resources & Next Steps + +==== Resources + +* Workshop recording (48 hours) +* GitHub repository +* Documentation +* Community forum + +==== Next Steps + +[arabic] +. Try the techniques +. Join GitHub Discussions +. Attend office hours (June 12) +. Participate in plugin contest + +=== Slide 11: Thank You! + +* Contact: workshop@panll.hyperpolymath.dev +* GitHub: github.com/hyperpolymath/panll +* Twitter: @panll_project + +=== Backup Slides + +==== Troubleshooting Guide + +[arabic] +. VeriSimDB connection issues +. Burble synchronization problems +. Identity load failures +. Performance optimization + +==== Advanced Topics + +* Custom conflict resolution +* Advanced caching strategies +* Plugin development deep dive +* Performance tuning diff --git a/workshop/presentation/slides.md b/workshop/presentation/slides.md deleted file mode 100644 index c3d2cba5..00000000 --- a/workshop/presentation/slides.md +++ /dev/null @@ -1,129 +0,0 @@ -# PanLL v0.2.0 Workshop: Advanced Identity Management & Team Collaboration - -## Slide 1: Title Slide -- **Title**: Mastering PanLL v0.2.0 -- **Subtitle**: Advanced Identity Management & Team Collaboration -- **Date**: June 5, 2024 -- **Speakers**: Jonathan, Claude, Vibe, Gemini - -## Slide 2: Workshop Agenda -1. Welcome & Introduction (10 min) -2. Identity Management Architecture (20 min) -3. Advanced Team Collaboration (20 min) -4. Automation & Integration (20 min) -5. Extending PanLL (20 min) -6. Q&A Session (20 min) -7. Wrap-up & Next Steps (10 min) - -## Slide 3: About PanLL v0.2.0 -- **Connected Workbench** release -- Key features: - - System tray integration - - Burble/Gossamer service toggling - - Identity state capture with VeriSimDB - - Team replication capabilities - -## Slide 4: Identity Management Architecture -### Storage Layer -- VeriSimDB (primary) -- Filesystem fallback -- Cache optimization - -### Performance -- LRU caching -- Batch operations -- Compression techniques - -## Slide 5: Identity Snapshot Structure -```json -{ - "panels": [...], - "settings": {...}, - "service_urls": {...}, - "metadata": {...}, - "timestamp": "..." -} -``` - -## Slide 6: Team Collaboration with Burble -### Architecture -- Broadcast protocol -- Security model -- Conflict resolution - -### Workflows -- Team onboarding -- Project synchronization -- Access control patterns - -## Slide 7: Automation Techniques -### CLI Power User Tips -```bash -# Batch save all identities -panll identity save-all - -# Broadcast to team -panll team broadcast --all -``` - -### Scripting Examples -```javascript -// JavaScript API -const panll = require('panll-client'); -await panll.identity.save('work-config'); -``` - -## Slide 8: Extending PanLL -### Plugin System -- Architecture overview -- Plugin API -- Lifecycle hooks - -### Custom Storage Backends -```rust -// Example S3 backend -struct S3Backend; -impl StorageBackend for S3Backend { - fn save(&self, data: &[u8]) -> Result<()> { - // S3 implementation - } -} -``` - -## Slide 9: Q&A Session -- Open floor for questions -- Troubleshooting common issues -- Roadmap discussion -- Community contributions - -## Slide 10: Resources & Next Steps -### Resources -- Workshop recording (48 hours) -- GitHub repository -- Documentation -- Community forum - -### Next Steps -1. Try the techniques -2. Join GitHub Discussions -3. Attend office hours (June 12) -4. Participate in plugin contest - -## Slide 11: Thank You! -- Contact: workshop@panll.hyperpolymath.dev -- GitHub: github.com/hyperpolymath/panll -- Twitter: @panll_project - -## Backup Slides - -### Troubleshooting Guide -1. VeriSimDB connection issues -2. Burble synchronization problems -3. Identity load failures -4. Performance optimization - -### Advanced Topics -- Custom conflict resolution -- Advanced caching strategies -- Plugin development deep dive -- Performance tuning \ No newline at end of file diff --git a/workshop/speaker-coordination.adoc b/workshop/speaker-coordination.adoc new file mode 100644 index 00000000..b676d192 --- /dev/null +++ b/workshop/speaker-coordination.adoc @@ -0,0 +1,323 @@ +== Workshop Speaker Coordination + +=== Speaker Contact Information + +==== Jonathan D.A. Jewell (Project Lead) + +* *Email*: jonathan@hyperpolymath.dev +* *Phone*: +1 (555) 123-4567 +* *Timezone*: UTC-5 (Eastern Time) +* *Availability*: Weekdays 9AM-5PM UTC-5 + +==== Claude (Backend Architect) + +* *Email*: claude@hyperpolymath.dev +* *Phone*: +1 (555) 234-5678 +* *Timezone*: UTC-8 (Pacific Time) +* *Availability*: Weekdays 10AM-6PM UTC-8 + +==== Vibe (Frontend Lead) + +* *Email*: vibe@hyperpolymath.dev +* *Phone*: +1 (555) 345-6789 +* *Timezone*: UTC-5 (Eastern Time) +* *Availability*: Weekdays 8AM-4PM UTC-5 + +==== Gemini (DevOps Engineer) + +* *Email*: gemini@hyperpolymath.dev +* *Phone*: +1 (555) 456-7890 +* *Timezone*: UTC-7 (Mountain Time) +* *Availability*: Weekdays 9AM-5PM UTC-7 + +=== Workshop Preparation Timeline + +==== May 20, 2024 - Initial Briefing + +* *Time*: 14:00 UTC +* *Duration*: 60 minutes +* *Agenda*: +** Workshop overview and objectives +** Session breakdown and responsibilities +** Technical requirements review +** Q&A about expectations + +==== May 27, 2024 - Content Review + +* *Time*: 14:00 UTC +* *Duration*: 90 minutes +* *Agenda*: +** Review presentation slides +** Demo walkthroughs +** Content coordination +** Timing adjustments + +==== June 3, 2024 - Technical Rehearsal + +* *Time*: 14:00 UTC +* *Duration*: 120 minutes +* *Agenda*: +** Full workshop dry run +** Technical setup testing +** Demo verification +** Transition practice +** Q&A simulation + +=== Individual Session Responsibilities + +==== Jonathan D.A. Jewell + +* *Sessions*: Welcome & Introduction, Q&A Moderation, Workshop Wrap-up +* *Preparation*: +** Prepare opening remarks +** Develop community guidelines +** Prepare Q&A questions +** Create closing summary + +==== Claude + +* *Sessions*: Identity Management Architecture, Extending PanLL +* *Preparation*: +** Prepare deep dive on storage layer +** Develop performance benchmarks +** Create plugin development demo +** Prepare custom storage backend example + +==== Vibe + +* *Sessions*: Advanced Team Collaboration +* *Preparation*: +** Develop Burble integration explanation +** Create team workflow simulation +** Prepare conflict resolution demo +** Develop access control examples + +==== Gemini + +* *Sessions*: Automation & Integration +* *Preparation*: +** Prepare CLI techniques demonstration +** Develop scripting examples +** Create CI/CD integration demo +** Prepare custom script examples + +=== Technical Requirements for Speakers + +==== Hardware + +* High-quality microphone (USB preferred) +* HD webcam (1080p recommended) +* Dual monitors (recommended) +* Backup internet connection +* Wired network connection (preferred) + +==== Software + +* Zoom Client (latest version) +* OBS Studio (for screen sharing) +* PanLL v0.2.0 with demo data +* VeriSimDB running +* Burble service running +* VS Code or preferred IDE + +==== Environment Setup + +[source,bash] +---- +# Install/upgrade to v0.2.0 +wget https://github.com/hyperpolymath/panll/releases/download/v0.2.0/panll-v0.2.0-linux-x86_64.tar.gz +tar -xzf panll-v0.2.0-linux-x86_64.tar.gz +cd panll-v0.2.0-linux-x86_64 +sudo ./install.sh + +# Start services +sudo systemctl start verisimdb +sudo systemctl start burble +sudo systemctl start panll + +# Verify installation +panll --version # Should show v0.2.0 +curl http://localhost:8080/health # Should return OK +---- + +=== Demo Preparation Checklist + +==== Identity Management (Claude) + +* [ ] Identity snapshot structure visualization +* [ ] VeriSimDB vs filesystem performance comparison +* [ ] Cache hit rate monitoring demo +* [ ] Fallback mechanism demonstration + +==== Team Collaboration (Vibe) + +* [ ] Burble broadcast simulation +* [ ] Team workflow with 3+ members +* [ ] Conflict resolution scenario +* [ ] Access control setup and testing + +==== Automation (Gemini) + +* [ ] Batch snapshot processing +* [ ] Custom script execution +* [ ] CI pipeline integration demo +* [ ] Programmatic access examples + +==== Extending PanLL (Claude) + +* [ ] Live plugin development +* [ ] Custom S3 storage backend +* [ ] UI extension example +* [ ] Plugin lifecycle demonstration + +=== Communication Protocol + +==== Primary Communication + +* *Platform*: Zoom (workshop day) +* *Backup*: Discord (#workshop-speakers channel) +* *Emergency*: WhatsApp group + +==== Signal Protocol + +* *Thumbs Up*: Ready to proceed +* *Thumbs Down*: Technical issue +* *Raise Hand*: Need to speak privately +* *Chat Message*: "`EXTEND 5`" - Request 5 minute extension +* *Chat Message*: "`SKIP`" - Skip to next section + +=== Contingency Plans + +==== Speaker Unavailable + +[arabic] +. *Short delay (<15 min)*: Extend other sessions +. *Long delay (>15 min)*: Use pre-recorded segment +. *Complete absence*: Backup speaker takes over + +==== Technical Issues + +[arabic] +. *Audio problems*: Switch to backup microphone +. *Screen sharing failure*: Use pre-recorded demo +. *Internet dropout*: Switch to mobile hotspot +. *Zoom failure*: Move to YouTube Live backup + +==== Time Management + +[arabic] +. *Running over*: Prioritize Q&A, move less critical content to +follow-up +. *Running under*: Extended Q&A, additional demos, deeper dives + +=== Speaker Preparation Checklist + +==== Before May 20 Briefing + +* [ ] Review workshop agenda +* [ ] Familiarize with your session content +* [ ] Identify any questions or concerns +* [ ] Test your technical setup + +==== Before May 27 Content Review + +* [ ] Complete first draft of slides +* [ ] Prepare demo scripts +* [ ] Test all demos locally +* [ ] Identify timing for each section + +==== Before June 3 Technical Rehearsal + +* [ ] Finalize all slides +* [ ] Complete all demos +* [ ] Prepare speaker notes +* [ ] Test full session flow +* [ ] Prepare backup materials + +==== Before Workshop Day + +* [ ] Confirm all software installed +* [ ] Test audio/video quality +* [ ] Verify internet connection stability +* [ ] Prepare backup internet option +* [ ] Review contingency plans +* [ ] Get good night’s sleep! + +=== Workshop Day Schedule (June 5, 2024) + +==== Speaker Arrival & Setup + +* *13:30 UTC*: Speakers join Zoom +* *13:30-13:45 UTC*: Final technical check +* *13:45-13:50 UTC*: Speaker briefing +* *13:50-13:55 UTC*: Attendee welcome + +==== Workshop Flow + +* *14:00-14:10 UTC*: Welcome & Introduction (Jonathan) +* *14:10-14:30 UTC*: Identity Management (Claude) +* *14:30-14:50 UTC*: Team Collaboration (Vibe) +* *14:50-15:10 UTC*: Automation & Integration (Gemini) +* *15:10-15:30 UTC*: Extending PanLL (Claude) +* *15:30-15:50 UTC*: Q&A Session (Jonathan) +* *15:50-16:00 UTC*: Wrap-up & Next Steps (Jonathan) + +==== Post-Workshop + +* *16:00-16:15 UTC*: Speaker debrief +* *16:15 UTC*: Official wrap-up + +=== Post-Workshop Follow-up + +==== Speaker Responsibilities + +[arabic] +. *Within 24 hours*: +* Review session recording +* Note any corrections needed +* Identify Q&A follow-ups +. *Within 48 hours*: +* Provide final slides to organizer +* Share demo code/samples +* Submit any corrections +. *Within 1 week*: +* Review attendee feedback +* Prepare blog post summary +* Identify improvements for next workshop + +=== Contact Information + +==== Workshop Organizer + +* *Name*: Workshop Coordinator +* *Email*: workshop@panll.hyperpolymath.dev +* *Phone*: +1 (555) 987-6543 +* *Emergency*: +1 (555) 876-5432 + +==== Technical Support + +* *Email*: support@panll.hyperpolymath.dev +* *Phone*: +1 (555) 765-4321 +* *Discord*: #workshop-tech-support + +=== Important Notes + +[arabic] +. *Confidentiality*: All workshop materials are confidential until +public release +. *Recording*: Workshop will be recorded and made available to attendees +. *Code of Conduct*: All speakers must adhere to community guidelines +. *Backup Plans*: Always have backup materials and contingency plans +ready +. *Timing*: Respect time limits to ensure smooth workshop flow + +=== Speaker Agreement + +By participating as a speaker, I agree to: - [ ] Prepare thoroughly for +my assigned sessions - [ ] Attend all preparation meetings - [ ] Test +all technical requirements in advance - [ ] Follow the workshop code of +conduct - [ ] Respect time limits during the workshop - [ ] Provide +constructive feedback after the workshop - [ ] Make myself available for +reasonable follow-up questions + +*Speaker Signature*: _______________________ *Date*: _______________ diff --git a/workshop/speaker-coordination.md b/workshop/speaker-coordination.md deleted file mode 100644 index dcabcd20..00000000 --- a/workshop/speaker-coordination.md +++ /dev/null @@ -1,286 +0,0 @@ -# Workshop Speaker Coordination - -## Speaker Contact Information - -### Jonathan D.A. Jewell (Project Lead) -- **Email**: jonathan@hyperpolymath.dev -- **Phone**: +1 (555) 123-4567 -- **Timezone**: UTC-5 (Eastern Time) -- **Availability**: Weekdays 9AM-5PM UTC-5 - -### Claude (Backend Architect) -- **Email**: claude@hyperpolymath.dev -- **Phone**: +1 (555) 234-5678 -- **Timezone**: UTC-8 (Pacific Time) -- **Availability**: Weekdays 10AM-6PM UTC-8 - -### Vibe (Frontend Lead) -- **Email**: vibe@hyperpolymath.dev -- **Phone**: +1 (555) 345-6789 -- **Timezone**: UTC-5 (Eastern Time) -- **Availability**: Weekdays 8AM-4PM UTC-5 - -### Gemini (DevOps Engineer) -- **Email**: gemini@hyperpolymath.dev -- **Phone**: +1 (555) 456-7890 -- **Timezone**: UTC-7 (Mountain Time) -- **Availability**: Weekdays 9AM-5PM UTC-7 - -## Workshop Preparation Timeline - -### May 20, 2024 - Initial Briefing -- **Time**: 14:00 UTC -- **Duration**: 60 minutes -- **Agenda**: - - Workshop overview and objectives - - Session breakdown and responsibilities - - Technical requirements review - - Q&A about expectations - -### May 27, 2024 - Content Review -- **Time**: 14:00 UTC -- **Duration**: 90 minutes -- **Agenda**: - - Review presentation slides - - Demo walkthroughs - - Content coordination - - Timing adjustments - -### June 3, 2024 - Technical Rehearsal -- **Time**: 14:00 UTC -- **Duration**: 120 minutes -- **Agenda**: - - Full workshop dry run - - Technical setup testing - - Demo verification - - Transition practice - - Q&A simulation - -## Individual Session Responsibilities - -### Jonathan D.A. Jewell -- **Sessions**: Welcome & Introduction, Q&A Moderation, Workshop Wrap-up -- **Preparation**: - - Prepare opening remarks - - Develop community guidelines - - Prepare Q&A questions - - Create closing summary - -### Claude -- **Sessions**: Identity Management Architecture, Extending PanLL -- **Preparation**: - - Prepare deep dive on storage layer - - Develop performance benchmarks - - Create plugin development demo - - Prepare custom storage backend example - -### Vibe -- **Sessions**: Advanced Team Collaboration -- **Preparation**: - - Develop Burble integration explanation - - Create team workflow simulation - - Prepare conflict resolution demo - - Develop access control examples - -### Gemini -- **Sessions**: Automation & Integration -- **Preparation**: - - Prepare CLI techniques demonstration - - Develop scripting examples - - Create CI/CD integration demo - - Prepare custom script examples - -## Technical Requirements for Speakers - -### Hardware -- High-quality microphone (USB preferred) -- HD webcam (1080p recommended) -- Dual monitors (recommended) -- Backup internet connection -- Wired network connection (preferred) - -### Software -- Zoom Client (latest version) -- OBS Studio (for screen sharing) -- PanLL v0.2.0 with demo data -- VeriSimDB running -- Burble service running -- VS Code or preferred IDE - -### Environment Setup -```bash -# Install/upgrade to v0.2.0 -wget https://github.com/hyperpolymath/panll/releases/download/v0.2.0/panll-v0.2.0-linux-x86_64.tar.gz -tar -xzf panll-v0.2.0-linux-x86_64.tar.gz -cd panll-v0.2.0-linux-x86_64 -sudo ./install.sh - -# Start services -sudo systemctl start verisimdb -sudo systemctl start burble -sudo systemctl start panll - -# Verify installation -panll --version # Should show v0.2.0 -curl http://localhost:8080/health # Should return OK -``` - -## Demo Preparation Checklist - -### Identity Management (Claude) -- [ ] Identity snapshot structure visualization -- [ ] VeriSimDB vs filesystem performance comparison -- [ ] Cache hit rate monitoring demo -- [ ] Fallback mechanism demonstration - -### Team Collaboration (Vibe) -- [ ] Burble broadcast simulation -- [ ] Team workflow with 3+ members -- [ ] Conflict resolution scenario -- [ ] Access control setup and testing - -### Automation (Gemini) -- [ ] Batch snapshot processing -- [ ] Custom script execution -- [ ] CI pipeline integration demo -- [ ] Programmatic access examples - -### Extending PanLL (Claude) -- [ ] Live plugin development -- [ ] Custom S3 storage backend -- [ ] UI extension example -- [ ] Plugin lifecycle demonstration - -## Communication Protocol - -### Primary Communication -- **Platform**: Zoom (workshop day) -- **Backup**: Discord (#workshop-speakers channel) -- **Emergency**: WhatsApp group - -### Signal Protocol -- **Thumbs Up**: Ready to proceed -- **Thumbs Down**: Technical issue -- **Raise Hand**: Need to speak privately -- **Chat Message**: "EXTEND 5" - Request 5 minute extension -- **Chat Message**: "SKIP" - Skip to next section - -## Contingency Plans - -### Speaker Unavailable -1. **Short delay (<15 min)**: Extend other sessions -2. **Long delay (>15 min)**: Use pre-recorded segment -3. **Complete absence**: Backup speaker takes over - -### Technical Issues -1. **Audio problems**: Switch to backup microphone -2. **Screen sharing failure**: Use pre-recorded demo -3. **Internet dropout**: Switch to mobile hotspot -4. **Zoom failure**: Move to YouTube Live backup - -### Time Management -1. **Running over**: Prioritize Q&A, move less critical content to follow-up -2. **Running under**: Extended Q&A, additional demos, deeper dives - -## Speaker Preparation Checklist - -### Before May 20 Briefing -- [ ] Review workshop agenda -- [ ] Familiarize with your session content -- [ ] Identify any questions or concerns -- [ ] Test your technical setup - -### Before May 27 Content Review -- [ ] Complete first draft of slides -- [ ] Prepare demo scripts -- [ ] Test all demos locally -- [ ] Identify timing for each section - -### Before June 3 Technical Rehearsal -- [ ] Finalize all slides -- [ ] Complete all demos -- [ ] Prepare speaker notes -- [ ] Test full session flow -- [ ] Prepare backup materials - -### Before Workshop Day -- [ ] Confirm all software installed -- [ ] Test audio/video quality -- [ ] Verify internet connection stability -- [ ] Prepare backup internet option -- [ ] Review contingency plans -- [ ] Get good night's sleep! - -## Workshop Day Schedule (June 5, 2024) - -### Speaker Arrival & Setup -- **13:30 UTC**: Speakers join Zoom -- **13:30-13:45 UTC**: Final technical check -- **13:45-13:50 UTC**: Speaker briefing -- **13:50-13:55 UTC**: Attendee welcome - -### Workshop Flow -- **14:00-14:10 UTC**: Welcome & Introduction (Jonathan) -- **14:10-14:30 UTC**: Identity Management (Claude) -- **14:30-14:50 UTC**: Team Collaboration (Vibe) -- **14:50-15:10 UTC**: Automation & Integration (Gemini) -- **15:10-15:30 UTC**: Extending PanLL (Claude) -- **15:30-15:50 UTC**: Q&A Session (Jonathan) -- **15:50-16:00 UTC**: Wrap-up & Next Steps (Jonathan) - -### Post-Workshop -- **16:00-16:15 UTC**: Speaker debrief -- **16:15 UTC**: Official wrap-up - -## Post-Workshop Follow-up - -### Speaker Responsibilities -1. **Within 24 hours**: - - Review session recording - - Note any corrections needed - - Identify Q&A follow-ups - -2. **Within 48 hours**: - - Provide final slides to organizer - - Share demo code/samples - - Submit any corrections - -3. **Within 1 week**: - - Review attendee feedback - - Prepare blog post summary - - Identify improvements for next workshop - -## Contact Information - -### Workshop Organizer -- **Name**: Workshop Coordinator -- **Email**: workshop@panll.hyperpolymath.dev -- **Phone**: +1 (555) 987-6543 -- **Emergency**: +1 (555) 876-5432 - -### Technical Support -- **Email**: support@panll.hyperpolymath.dev -- **Phone**: +1 (555) 765-4321 -- **Discord**: #workshop-tech-support - -## Important Notes - -1. **Confidentiality**: All workshop materials are confidential until public release -2. **Recording**: Workshop will be recorded and made available to attendees -3. **Code of Conduct**: All speakers must adhere to community guidelines -4. **Backup Plans**: Always have backup materials and contingency plans ready -5. **Timing**: Respect time limits to ensure smooth workshop flow - -## Speaker Agreement - -By participating as a speaker, I agree to: -- [ ] Prepare thoroughly for my assigned sessions -- [ ] Attend all preparation meetings -- [ ] Test all technical requirements in advance -- [ ] Follow the workshop code of conduct -- [ ] Respect time limits during the workshop -- [ ] Provide constructive feedback after the workshop -- [ ] Make myself available for reasonable follow-up questions - -**Speaker Signature**: _______________________ -**Date**: _______________ \ No newline at end of file diff --git a/workshop/v0.2.0-advanced-usage.adoc b/workshop/v0.2.0-advanced-usage.adoc new file mode 100644 index 00000000..d9450b23 --- /dev/null +++ b/workshop/v0.2.0-advanced-usage.adoc @@ -0,0 +1,810 @@ +== PanLL v0.2.0 Community Workshop: Advanced Usage + +=== Workshop Details + +*Title*: Mastering PanLL v0.2.0: Advanced Identity Management & Team +Collaboration + +*Date*: June 5, 2024 + +*Time*: 14:00 - 16:00 UTC (Convert to your timezone) + +*Location*: Virtual (Zoom Webinar) + +*Registration*: https://panll.hyperpolymath.dev/workshop + +*Capacity*: 200 attendees + +*Cost*: Free + +=== Workshop Agenda + +==== 1. Welcome & Introduction (10 minutes) + +* Workshop overview +* Speaker introductions +* Housekeeping and Q&A format +* Community guidelines + +*Speaker*: Jonathan D.A. Jewell (Project Lead) + +==== 2. Deep Dive: Identity Management Architecture (20 minutes) + +* Under the hood: How identity snapshots work +* Storage layer: VeriSimDB + filesystem fallback +* Cache optimization strategies +* Performance benchmarks and tuning + +*Speaker*: Claude (Backend Architect) + +*Demo*: - Live coding: Extending identity management - Performance +comparison: v0.1.x vs v0.2.0 - Cache hit rate analysis + +==== 3. Advanced Team Collaboration (20 minutes) + +* Burble integration deep dive +* Real-time broadcasting patterns +* Team synchronization strategies +* Conflict resolution and merging + +*Speaker*: Vibe (Frontend Lead) + +*Demo*: - Team workflow simulation - Broadcast history analysis - +Conflict resolution scenarios + +==== 4. Automation & Integration (20 minutes) + +* CLI power user techniques +* Scripting identity operations +* CI/CD integration +* Custom storage backends + +*Speaker*: Gemini (DevOps Engineer) + +*Demo*: - Batch operations - Programmatic access examples - Custom S3 +backend implementation + +==== 5. Extending PanLL (20 minutes) + +* Plugin system architecture +* Building custom plugins +* Storage backend development +* UI extension patterns + +*Speaker*: Claude (Backend Architect) + +*Demo*: - Live plugin development - Custom storage backend - UI +extension example + +==== 6. Q&A Session (20 minutes) + +* Open floor for attendee questions +* Troubleshooting common issues +* Roadmap discussion +* Community contributions + +*Moderator*: Jonathan D.A. Jewell + +==== 7. Workshop Wrap-up & Next Steps (10 minutes) + +* Summary of key takeaways +* Resources and documentation +* Upcoming community events +* Call to action: Get involved! + +*Speaker*: Jonathan D.A. Jewell + +=== Workshop Materials + +==== Prerequisites + +*Software*: - PanLL v0.2.0 installed - VeriSimDB running - Burble +service running - Basic familiarity with PanLL interface + +*Hardware*: - Modern browser (Chrome/Firefox/Safari) - Stable internet +connection - Microphone (for interactive participants) + +==== Preparation + +[source,bash] +---- +# Install/upgrade to v0.2.0 +wget https://github.com/hyperpolymath/panll/releases/download/v0.2.0/panll-v0.2.0-linux-x86_64.tar.gz +tar -xzf panll-v0.2.0-linux-x86_64.tar.gz +cd panll-v0.2.0-linux-x86_64 +sudo ./install.sh + +# Start services +sudo systemctl start verisimdb +sudo systemctl start burble +sudo systemctl start panll + +# Verify installation +panll --version # Should show v0.2.0 +curl http://localhost:8080/health # Should return OK +---- + +==== Workshop Repository + +*GitHub*: https://github.com/hyperpolymath/panll-workshop-june-2024 + +*Contents*: - Workshop slides (PDF) - Code samples - Configuration +templates - Troubleshooting guide + +=== Speaker Bios + +==== Jonathan D.A. Jewell + +*Role*: Project Lead & Architect + +Jonathan is the creator and lead architect of PanLL. With 15 years of +experience in developer tools and ambient computing, he leads the vision +and direction of the project. Jonathan holds a PhD in Human-Computer +Interaction from The Open University. + +*Expertise*: System architecture, UX design, ambient computing + +==== Claude + +*Role*: Backend Architect + +Claude is the lead backend developer for PanLL, specializing in Rust +systems programming and distributed systems. With a background in +high-performance computing, Claude designed the Gossamer backend and +VeriSimDB integration. + +*Expertise*: Rust, Zig, distributed systems, performance optimization + +==== Vibe + +*Role*: Frontend Lead + +Vibe leads the frontend development team, bringing extensive experience +in ReScript, React, and real-time collaborative interfaces. Vibe +designed the identity management UI and Burble integration. + +*Expertise*: ReScript, React, real-time collaboration, UI/UX + +==== Gemini + +*Role*: DevOps Engineer + +Gemini specializes in deployment, automation, and CI/CD pipelines. With +experience in large-scale distributed systems, Gemini ensures PanLL’s +reliability and scalability. + +*Expertise*: DevOps, automation, CI/CD, observability + +=== Workshop Format + +==== Interactive Elements + +[arabic] +. *Live Demos*: Step-by-step demonstrations with audience participation +. *Q&A Sessions*: Dedicated time for attendee questions +. *Breakout Rooms*: Small group discussions (optional) +. *Live Coding*: Real-time implementation examples + +==== Engagement Rules + +* *Respect*: Be kind and considerate to all participants +* *Relevance*: Keep questions and comments on-topic +* *Conciseness*: Be brief to allow everyone to participate +* *Privacy*: No recording without permission + +=== Technical Requirements + +==== For Attendees + +*Minimum*: - PanLL v0.2.0 installed - Modern browser - Stable internet +(5Mbps+) + +*Recommended*: - Dual monitors (one for workshop, one for coding) - +IDE/text editor open - Terminal ready + +==== For Speakers + +*Equipment*: - High-quality microphone - HD webcam - Screen sharing +capability - Backup internet connection + +*Software*: - OBS Studio (for screen sharing) - Zoom client (latest +version) - PanLL v0.2.0 with demo data + +=== Workshop Outline (Detailed) + +==== Session 1: Identity Management Architecture (20 min) + +*Topics*: 1. Identity snapshot structure (5 min) - Panel state - +Settings - Service URLs - Metadata + +[arabic, start=2] +. Storage layer (5 min) +* VeriSimDB primary storage +* Filesystem fallback +* Cache implementation +. Performance optimization (5 min) +* LRU caching +* Batch operations +* Compression +. Q&A (5 min) + +*Demo*: - Save/load performance comparison - Cache hit rate monitoring - +Fallback mechanism + +==== Session 2: Advanced Team Collaboration (20 min) + +*Topics*: 1. Burble integration (5 min) - Architecture overview - +Broadcast protocol - Security model + +[arabic, start=2] +. Team workflows (5 min) +* Onboarding patterns +* Project synchronization +* Conflict resolution +. Advanced patterns (5 min) +* Selective broadcasting +* Broadcast history +* Access control +. Q&A (5 min) + +*Demo*: - Team broadcast simulation - Conflict resolution - Access +control setup + +==== Session 3: Automation & Integration (20 min) + +*Topics*: 1. CLI techniques (5 min) - Batch operations - Scripting +patterns - Automation tips + +[arabic, start=2] +. Programmatic access (5 min) +* JavaScript API +* Rust extensions +* FFI patterns +. CI/CD integration (5 min) +* Testing strategies +* Deployment patterns +* Monitoring +. Q&A (5 min) + +*Demo*: - Batch snapshot processing - Custom script example - CI +pipeline setup + +==== Session 4: Extending PanLL (20 min) + +*Topics*: 1. Plugin system (5 min) - Architecture - Plugin API - +Lifecycle + +[arabic, start=2] +. Storage backends (5 min) +* Interface requirements +* Example: S3 backend +* Testing +. UI extensions (5 min) +* Component patterns +* State management +* Styling +. Q&A (5 min) + +*Demo*: - Live plugin development - Custom storage backend - UI +extension + +=== Post-Workshop Resources + +==== Recording + +* Available 48 hours after workshop +* YouTube: https://youtube.com/panll[PanLL Channel] +* Private link for attendees + +==== Follow-up Q&A + +* GitHub Discussions thread +* Dedicated office hours (June 12) +* Email support + +==== Community Challenges + +[arabic] +. *Best Plugin Contest*: Submit your custom plugin +. *Performance Challenge*: Optimize snapshot operations +. *UI Extension Showcase*: Share your custom components + +=== Workshop Promotion + +==== Social Media Posts + +*Post 1 (Announcement)*: + +.... +🚀 Exciting news! Join our PanLL v0.2.0 Community Workshop on June 5th! + +🔹 Deep dive into identity management +🔹 Advanced team collaboration +🔹 Automation techniques +🔹 Extending PanLL + +📅 June 5, 14:00 UTC +📍 Virtual (Zoom) +🎟️ Free registration + +👉 panll.hyperpolymath.dev/workshop + +#PanLL #ConnectedWorkbench #DevTools +.... + +*Post 2 (Speaker Highlight)*: + +.... +Meet our workshop speakers! 🎤 + +👨💻 Jonathan D.A. Jewell - Project Lead +👨💻 Claude - Backend Architect +👩💻 Vibe - Frontend Lead +👨💻 Gemini - DevOps Engineer + +Learn from the experts who built PanLL v0.2.0! + +📅 June 5, 14:00 UTC +🎟️ panll.hyperpolymath.dev/workshop + +#PanLL #Workshop #LearnFromExperts +.... + +*Post 3 (Countdown)*: + +.... +⏳ Only 7 days until our PanLL v0.2.0 Workshop! + +🔥 What you'll learn: +- Master identity snapshots +- Team collaboration patterns +- Automation techniques +- Extending PanLL + +🎁 All attendees get: +- Workshop recording +- Code samples +- Exclusive Q&A +- Community badge + +📅 June 5, 14:00 UTC +🎟️ panll.hyperpolymath.dev/workshop + +#PanLL #Countdown #DontMissOut +.... + +==== Email Campaign + +*Subject*: Master PanLL v0.2.0 - Join Our Community Workshop + +*Body*: + +.... +Hi [First Name], + +We're excited to invite you to our PanLL v0.2.0 Community Workshop on June 5th! + +**Why Attend?** + +✅ **Deep Dive**: Learn advanced identity management techniques from the core team +✅ **Hands-on**: Live coding sessions and practical demonstrations +✅ **Q&A**: Get your questions answered by PanLL's architects +✅ **Networking**: Connect with other PanLL power users + +**What You'll Learn**: + +🔹 Identity Management Architecture + - Storage layer deep dive + - Performance optimization + - Cache strategies + +🔹 Advanced Team Collaboration + - Burble integration patterns + - Real-time broadcasting + - Conflict resolution + +🔹 Automation & Integration + - CLI power techniques + - Scripting identity operations + - CI/CD integration + +🔹 Extending PanLL + - Plugin development + - Custom storage backends + - UI extensions + +**Workshop Details**: + +📅 Date: June 5, 2024 +⏰ Time: 14:00 - 16:00 UTC +📍 Location: Virtual (Zoom) +🎟️ Cost: Free + +**Prepare for the Workshop**: + +1. Install PanLL v0.2.0 +2. Review the blog post: panll.hyperpolymath.dev/blog/v0.2.0-release +3. Watch the tutorial video: [Coming Soon] +4. Bring your questions! + +**Register Now**: +[👉 Register for Free](https://panll.hyperpolymath.dev/workshop) + +We look forward to seeing you there! + +Best regards, +The PanLL Team +.... + +=== Workshop Checklist + +==== For Organizers + +* [ ] Finalize agenda and timings +* [ ] Confirm all speakers +* [ ] Test Zoom setup and recordings +* [ ] Prepare backup internet connection +* [ ] Set up registration system +* [ ] Create workshop repository +* [ ] Prepare slide deck +* [ ] Test all demos +* [ ] Set up Q&A system +* [ ] Prepare attendee welcome package + +==== For Attendees + +* [ ] Register for workshop +* [ ] Install PanLL v0.2.0 +* [ ] Review prerequisites +* [ ] Test your setup +* [ ] Prepare questions +* [ ] Block calendar +* [ ] Join community + +=== Post-Workshop Follow-up + +==== Attendee Survey + +[source,markdown] +---- +# PanLL v0.2.0 Workshop Feedback + +Thank you for attending our workshop! We'd love your feedback. + +## Overall Experience + +😊 Very satisfied +😐 Satisfied +😕 Neutral +😟 Dissatisfied +😠 Very dissatisfied + +## Content Quality + +1. Relevance to your needs: ⭐️⭐️⭐️⭐️⭐️ +2. Depth of coverage: ⭐️⭐️⭐️⭐️⭐️ +3. Practical value: ⭐️⭐️⭐️⭐️⭐️ + +## Speaker Quality + +1. Clarity: ⭐️⭐️⭐️⭐️⭐️ +2. Knowledge: ⭐️⭐️⭐️⭐️⭐️ +3. Engagement: ⭐️⭐️⭐️⭐️⭐️ + +## What Was Most Valuable? + +- [ ] Identity management architecture +- [ ] Team collaboration patterns +- [ ] Automation techniques +- [ ] Extending PanLL +- [ ] Q&A session + +## What Could Be Improved? + +- [ ] More hands-on exercises +- [ ] Longer Q&A time +- [ ] More advanced topics +- [ ] Slower pace +- [ ] More beginner content + +## Additional Feedback + +[Open text field] + +## Would You Recommend? + +- [ ] Yes, absolutely +- [ ] Yes, with reservations +- [ ] Neutral +- [ ] No + +## Stay Connected + +- [ ] Join our mailing list +- [ ] Follow on GitHub +- [ ] Join community discussions +- [ ] Attend future events + +[Submit Feedback] +---- + +==== Follow-up Email + +*Subject*: Thank You for Attending! + Workshop Resources + +*Body*: + +.... +Hi [First Name], + +Thank you for attending our PanLL v0.2.0 Community Workshop! We hope you found it valuable. + +**Workshop Resources**: + +📚 **Slides**: [Download PDF](https://panll.hyperpolymath.dev/workshop/slides) +💻 **Code Samples**: [GitHub Repository](https://github.com/hyperpolymath/panll-workshop-june-2024) +📹 **Recording**: [Watch on YouTube](https://youtube.com/panll) (available in 48 hours) +📖 **Documentation**: [panll.hyperpolymath.dev/docs](https://panll.hyperpolymath.dev/docs) + +**Next Steps**: + +1. **Try It Out**: Apply what you learned to your PanLL setup +2. **Join the Community**: [GitHub Discussions](https://github.com/hyperpolymath/panll/discussions) +3. **Give Feedback**: [Survey Link] +4. **Stay Updated**: Follow us for future events + +**Upcoming Events**: + +📅 **Office Hours**: June 12, 14:00 UTC + - Q&A with the PanLL team + - [Register Here](https://panll.hyperpolymath.dev/office-hours) + +📅 **Plugin Contest**: June 15 - July 15 + - Build and submit your custom plugin + - Prizes for best submissions + - [Contest Details](https://panll.hyperpolymath.dev/plugin-contest) + +**Community Challenges**: + +1. **Best Plugin**: Submit your custom plugin by July 15 +2. **Performance**: Optimize snapshot operations +3. **UI Extension**: Create innovative custom components + +**Prizes**: +- 🥇 1st Place: PanLL Premium Support (6 months) +- 🥈 2nd Place: PanLL Swag Pack +- 🥉 3rd Place: Feature spotlight in blog + +We'd love your feedback! Please take 2 minutes to complete our survey: + +[👉 Take Survey](https://panll.hyperpolymath.dev/workshop-feedback) + +Thank you again for being part of our community! + +Best regards, +The PanLL Team +.... + +=== Workshop Metrics + +==== Success Metrics + +[arabic] +. *Attendance*: Target 150-200 attendees +. *Engagement*: 80%+ participation in Q&A +. *Satisfaction*: 4.5/5 average rating +. *Follow-up*: 30%+ survey response rate + +==== Tracking + +[source,json] +---- +{ + "registrations": 187, + "attendees": 162, + "completion_rate": 0.87, + "questions_asked": 42, + "average_rating": 4.7, + "survey_responses": 58, + "follow_up_attendance": 38 +} +---- + +=== Contingency Plans + +==== Technical Issues + +[arabic] +. *Zoom Failure*: +* Backup: YouTube Live stream +* Communication: Email + Discord announcement +* Recording: Local backup +. *Speaker Dropout*: +* Backup speakers ready +* Pre-recorded segments available +* Extended Q&A +. *Demo Failures*: +* Pre-recorded fallback demos +* Simplified alternative examples +* Focus on concepts + +==== Low Attendance + +[arabic] +. *Reschedule*: Offer alternative date +. *Record*: Provide recording to registrants +. *Content*: Repurpose as blog/tutorial + +==== Time Management + +[arabic] +. *Running Over*: Prioritize Q&A, move less critical content to +follow-up +. *Running Under*: Extended Q&A, additional demos, deeper dives + +=== Workshop Repository Structure + +.... +panll-workshop-june-2024/ +├── README.md +├── agenda/ +│ ├── detailed.md +│ └── quick-reference.md +├── slides/ +│ ├── panll-workshop.pdf +│ └── panll-workshop.pptx +├── demos/ +│ ├── identity-management/ +│ ├── team-collaboration/ +│ ├── automation/ +│ └── extending/ +├── code-samples/ +│ ├── rust/ +│ ├── rescript/ +│ └── javascript/ +├── templates/ +│ ├── configuration.toml +│ └── plugin-template.rs +├── troubleshooting/ +│ └── guide.md +├── LICENSE +└── CONTRIBUTING.md +.... + +=== Workshop FAQ + +==== Registration + +*Q: Is the workshop really free?* A: Yes! The workshop is completely +free. We believe in open access to knowledge. + +*Q: Will the workshop be recorded?* A: Yes, the recording will be +available 48 hours after the workshop. + +*Q: Do I need to prepare anything?* A: We recommend installing PanLL +v0.2.0 and reviewing the blog post, but it’s not required. + +==== Technical + +*Q: What if I can’t install PanLL v0.2.0?* A: You can still attend! The +concepts apply to all versions, and we’ll provide guidance. + +*Q: Will the demos work on Windows/macOS?* A: The workshop focuses on +Linux, but concepts apply to all platforms. We’ll note differences. + +*Q: What if I miss part of the workshop?* A: The recording will be +available, and we’ll provide timestamps for each section. + +==== Content + +*Q: Is this workshop for beginners or advanced users?* A: The workshop +covers advanced topics but explains concepts clearly. Basic PanLL +knowledge is helpful but not required. + +*Q: Will you cover [specific topic]?* A: Check the agenda above. If not +listed, ask in the Q&A session! + +*Q: Can I ask questions during the workshop?* A: Absolutely! We have +dedicated Q&A time and will answer questions throughout. + +==== After the Workshop + +*Q: How can I get the slides/code samples?* A: Everything will be in the +workshop repository: github.com/hyperpolymath/panll-workshop-june-2024 + +*Q: Will there be more workshops?* A: Yes! We plan quarterly workshops. +Follow us for announcements. + +*Q: How can I suggest topics for future workshops?* A: Join our GitHub +Discussions and post your ideas! + +=== Workshop Promotion Timeline + +[source,mermaid] +---- +gantt + title Workshop Promotion Timeline + dateFormat YYYY-MM-DD + section Preparation + Finalize agenda :a1, 2024-05-01, 7d + Confirm speakers :a2, after a1, 3d + Create materials :a3, after a2, 10d + Test technical setup :a4, after a3, 3d + section Promotion + Announcement post :2024-05-10, 1d + Speaker highlights :2024-05-15, 1d + Countdown posts :2024-05-20, 7d + Email campaign :2024-05-22, 1d + Reminder emails :2024-06-03, 1d + Final reminder :2024-06-04, 1d + section Workshop + Workshop day :2024-06-05, 1d + section Follow-up + Send recording :2024-06-07, 1d + Send survey :2024-06-08, 1d + Office hours :2024-06-12, 1d +---- + +=== Final Checklist + +==== 1 Week Before + +* [ ] Finalize all content +* [ ] Test all demos +* [ ] Confirm all speakers +* [ ] Set up registration system +* [ ] Create workshop repository +* [ ] Schedule social media posts +* [ ] Prepare backup materials + +==== 3 Days Before + +* [ ] Send reminder emails +* [ ] Post final countdown +* [ ] Test Zoom setup +* [ ] Prepare speaker briefing +* [ ] Set up Q&A system +* [ ] Prepare attendee guide + +==== 1 Day Before + +* [ ] Final technical rehearsal +* [ ] Send final reminder +* [ ] Prepare backup internet +* [ ] Charge all equipment +* [ ] Set up monitoring +* [ ] Prepare welcome message + +==== Workshop Day + +* [ ] Start early for setup +* [ ] Welcome attendees +* [ ] Monitor chat for questions +* [ ] Record session +* [ ] Manage time carefully +* [ ] Thank everyone + +==== After Workshop + +* [ ] Upload recording +* [ ] Send thank-you emails +* [ ] Share resources +* [ ] Analyze feedback +* [ ] Plan next workshop + +=== Conclusion + +This workshop plan provides a comprehensive structure for our PanLL +v0.2.0 Community Workshop. With clear objectives, detailed content, and +thorough preparation, we’re set to deliver an engaging and valuable +experience for our community. + +*Next Steps*: 1. Finalize workshop agenda 2. Confirm speaker +availability 3. Create and test all demos 4. Set up registration system +5. Begin promotion campaign + +The workshop will establish PanLL v0.2.0 as the leading solution for +collaborative workbench management and set the stage for our growing +community. + +*Status*: Ready for finalization and execution 🚀 diff --git a/workshop/v0.2.0-advanced-usage.md b/workshop/v0.2.0-advanced-usage.md deleted file mode 100644 index 1bfb7508..00000000 --- a/workshop/v0.2.0-advanced-usage.md +++ /dev/null @@ -1,818 +0,0 @@ -# PanLL v0.2.0 Community Workshop: Advanced Usage - -## Workshop Details - -**Title**: Mastering PanLL v0.2.0: Advanced Identity Management & Team Collaboration - -**Date**: June 5, 2024 - -**Time**: 14:00 - 16:00 UTC (Convert to your timezone) - -**Location**: Virtual (Zoom Webinar) - -**Registration**: [https://panll.hyperpolymath.dev/workshop](https://panll.hyperpolymath.dev/workshop) - -**Capacity**: 200 attendees - -**Cost**: Free - -## Workshop Agenda - -### 1. Welcome & Introduction (10 minutes) -- Workshop overview -- Speaker introductions -- Housekeeping and Q&A format -- Community guidelines - -**Speaker**: Jonathan D.A. Jewell (Project Lead) - -### 2. Deep Dive: Identity Management Architecture (20 minutes) -- Under the hood: How identity snapshots work -- Storage layer: VeriSimDB + filesystem fallback -- Cache optimization strategies -- Performance benchmarks and tuning - -**Speaker**: Claude (Backend Architect) - -**Demo**: -- Live coding: Extending identity management -- Performance comparison: v0.1.x vs v0.2.0 -- Cache hit rate analysis - -### 3. Advanced Team Collaboration (20 minutes) -- Burble integration deep dive -- Real-time broadcasting patterns -- Team synchronization strategies -- Conflict resolution and merging - -**Speaker**: Vibe (Frontend Lead) - -**Demo**: -- Team workflow simulation -- Broadcast history analysis -- Conflict resolution scenarios - -### 4. Automation & Integration (20 minutes) -- CLI power user techniques -- Scripting identity operations -- CI/CD integration -- Custom storage backends - -**Speaker**: Gemini (DevOps Engineer) - -**Demo**: -- Batch operations -- Programmatic access examples -- Custom S3 backend implementation - -### 5. Extending PanLL (20 minutes) -- Plugin system architecture -- Building custom plugins -- Storage backend development -- UI extension patterns - -**Speaker**: Claude (Backend Architect) - -**Demo**: -- Live plugin development -- Custom storage backend -- UI extension example - -### 6. Q&A Session (20 minutes) -- Open floor for attendee questions -- Troubleshooting common issues -- Roadmap discussion -- Community contributions - -**Moderator**: Jonathan D.A. Jewell - -### 7. Workshop Wrap-up & Next Steps (10 minutes) -- Summary of key takeaways -- Resources and documentation -- Upcoming community events -- Call to action: Get involved! - -**Speaker**: Jonathan D.A. Jewell - -## Workshop Materials - -### Prerequisites - -**Software**: -- PanLL v0.2.0 installed -- VeriSimDB running -- Burble service running -- Basic familiarity with PanLL interface - -**Hardware**: -- Modern browser (Chrome/Firefox/Safari) -- Stable internet connection -- Microphone (for interactive participants) - -### Preparation - -```bash -# Install/upgrade to v0.2.0 -wget https://github.com/hyperpolymath/panll/releases/download/v0.2.0/panll-v0.2.0-linux-x86_64.tar.gz -tar -xzf panll-v0.2.0-linux-x86_64.tar.gz -cd panll-v0.2.0-linux-x86_64 -sudo ./install.sh - -# Start services -sudo systemctl start verisimdb -sudo systemctl start burble -sudo systemctl start panll - -# Verify installation -panll --version # Should show v0.2.0 -curl http://localhost:8080/health # Should return OK -``` - -### Workshop Repository - -**GitHub**: [https://github.com/hyperpolymath/panll-workshop-june-2024](https://github.com/hyperpolymath/panll-workshop-june-2024) - -**Contents**: -- Workshop slides (PDF) -- Code samples -- Configuration templates -- Troubleshooting guide - -## Speaker Bios - -### Jonathan D.A. Jewell -**Role**: Project Lead & Architect - -Jonathan is the creator and lead architect of PanLL. With 15 years of experience in developer tools and ambient computing, he leads the vision and direction of the project. Jonathan holds a PhD in Human-Computer Interaction from The Open University. - -**Expertise**: System architecture, UX design, ambient computing - -### Claude -**Role**: Backend Architect - -Claude is the lead backend developer for PanLL, specializing in Rust systems programming and distributed systems. With a background in high-performance computing, Claude designed the Gossamer backend and VeriSimDB integration. - -**Expertise**: Rust, Zig, distributed systems, performance optimization - -### Vibe -**Role**: Frontend Lead - -Vibe leads the frontend development team, bringing extensive experience in ReScript, React, and real-time collaborative interfaces. Vibe designed the identity management UI and Burble integration. - -**Expertise**: ReScript, React, real-time collaboration, UI/UX - -### Gemini -**Role**: DevOps Engineer - -Gemini specializes in deployment, automation, and CI/CD pipelines. With experience in large-scale distributed systems, Gemini ensures PanLL's reliability and scalability. - -**Expertise**: DevOps, automation, CI/CD, observability - -## Workshop Format - -### Interactive Elements - -1. **Live Demos**: Step-by-step demonstrations with audience participation -2. **Q&A Sessions**: Dedicated time for attendee questions -3. **Breakout Rooms**: Small group discussions (optional) -4. **Live Coding**: Real-time implementation examples - -### Engagement Rules - -- **Respect**: Be kind and considerate to all participants -- **Relevance**: Keep questions and comments on-topic -- **Conciseness**: Be brief to allow everyone to participate -- **Privacy**: No recording without permission - -## Technical Requirements - -### For Attendees - -**Minimum**: -- PanLL v0.2.0 installed -- Modern browser -- Stable internet (5Mbps+) - -**Recommended**: -- Dual monitors (one for workshop, one for coding) -- IDE/text editor open -- Terminal ready - -### For Speakers - -**Equipment**: -- High-quality microphone -- HD webcam -- Screen sharing capability -- Backup internet connection - -**Software**: -- OBS Studio (for screen sharing) -- Zoom client (latest version) -- PanLL v0.2.0 with demo data - -## Workshop Outline (Detailed) - -### Session 1: Identity Management Architecture (20 min) - -**Topics**: -1. Identity snapshot structure (5 min) - - Panel state - - Settings - - Service URLs - - Metadata - -2. Storage layer (5 min) - - VeriSimDB primary storage - - Filesystem fallback - - Cache implementation - -3. Performance optimization (5 min) - - LRU caching - - Batch operations - - Compression - -4. Q&A (5 min) - -**Demo**: -- Save/load performance comparison -- Cache hit rate monitoring -- Fallback mechanism - -### Session 2: Advanced Team Collaboration (20 min) - -**Topics**: -1. Burble integration (5 min) - - Architecture overview - - Broadcast protocol - - Security model - -2. Team workflows (5 min) - - Onboarding patterns - - Project synchronization - - Conflict resolution - -3. Advanced patterns (5 min) - - Selective broadcasting - - Broadcast history - - Access control - -4. Q&A (5 min) - -**Demo**: -- Team broadcast simulation -- Conflict resolution -- Access control setup - -### Session 3: Automation & Integration (20 min) - -**Topics**: -1. CLI techniques (5 min) - - Batch operations - - Scripting patterns - - Automation tips - -2. Programmatic access (5 min) - - JavaScript API - - Rust extensions - - FFI patterns - -3. CI/CD integration (5 min) - - Testing strategies - - Deployment patterns - - Monitoring - -4. Q&A (5 min) - -**Demo**: -- Batch snapshot processing -- Custom script example -- CI pipeline setup - -### Session 4: Extending PanLL (20 min) - -**Topics**: -1. Plugin system (5 min) - - Architecture - - Plugin API - - Lifecycle - -2. Storage backends (5 min) - - Interface requirements - - Example: S3 backend - - Testing - -3. UI extensions (5 min) - - Component patterns - - State management - - Styling - -4. Q&A (5 min) - -**Demo**: -- Live plugin development -- Custom storage backend -- UI extension - -## Post-Workshop Resources - -### Recording -- Available 48 hours after workshop -- YouTube: [PanLL Channel](https://youtube.com/panll) -- Private link for attendees - -### Follow-up Q&A -- GitHub Discussions thread -- Dedicated office hours (June 12) -- Email support - -### Community Challenges -1. **Best Plugin Contest**: Submit your custom plugin -2. **Performance Challenge**: Optimize snapshot operations -3. **UI Extension Showcase**: Share your custom components - -## Workshop Promotion - -### Social Media Posts - -**Post 1 (Announcement)**: -``` -🚀 Exciting news! Join our PanLL v0.2.0 Community Workshop on June 5th! - -🔹 Deep dive into identity management -🔹 Advanced team collaboration -🔹 Automation techniques -🔹 Extending PanLL - -📅 June 5, 14:00 UTC -📍 Virtual (Zoom) -🎟️ Free registration - -👉 panll.hyperpolymath.dev/workshop - -#PanLL #ConnectedWorkbench #DevTools -``` - -**Post 2 (Speaker Highlight)**: -``` -Meet our workshop speakers! 🎤 - -👨💻 Jonathan D.A. Jewell - Project Lead -👨💻 Claude - Backend Architect -👩💻 Vibe - Frontend Lead -👨💻 Gemini - DevOps Engineer - -Learn from the experts who built PanLL v0.2.0! - -📅 June 5, 14:00 UTC -🎟️ panll.hyperpolymath.dev/workshop - -#PanLL #Workshop #LearnFromExperts -``` - -**Post 3 (Countdown)**: -``` -⏳ Only 7 days until our PanLL v0.2.0 Workshop! - -🔥 What you'll learn: -- Master identity snapshots -- Team collaboration patterns -- Automation techniques -- Extending PanLL - -🎁 All attendees get: -- Workshop recording -- Code samples -- Exclusive Q&A -- Community badge - -📅 June 5, 14:00 UTC -🎟️ panll.hyperpolymath.dev/workshop - -#PanLL #Countdown #DontMissOut -``` - -### Email Campaign - -**Subject**: Master PanLL v0.2.0 - Join Our Community Workshop - -**Body**: -``` -Hi [First Name], - -We're excited to invite you to our PanLL v0.2.0 Community Workshop on June 5th! - -**Why Attend?** - -✅ **Deep Dive**: Learn advanced identity management techniques from the core team -✅ **Hands-on**: Live coding sessions and practical demonstrations -✅ **Q&A**: Get your questions answered by PanLL's architects -✅ **Networking**: Connect with other PanLL power users - -**What You'll Learn**: - -🔹 Identity Management Architecture - - Storage layer deep dive - - Performance optimization - - Cache strategies - -🔹 Advanced Team Collaboration - - Burble integration patterns - - Real-time broadcasting - - Conflict resolution - -🔹 Automation & Integration - - CLI power techniques - - Scripting identity operations - - CI/CD integration - -🔹 Extending PanLL - - Plugin development - - Custom storage backends - - UI extensions - -**Workshop Details**: - -📅 Date: June 5, 2024 -⏰ Time: 14:00 - 16:00 UTC -📍 Location: Virtual (Zoom) -🎟️ Cost: Free - -**Prepare for the Workshop**: - -1. Install PanLL v0.2.0 -2. Review the blog post: panll.hyperpolymath.dev/blog/v0.2.0-release -3. Watch the tutorial video: [Coming Soon] -4. Bring your questions! - -**Register Now**: -[👉 Register for Free](https://panll.hyperpolymath.dev/workshop) - -We look forward to seeing you there! - -Best regards, -The PanLL Team -``` - -## Workshop Checklist - -### For Organizers - -- [ ] Finalize agenda and timings -- [ ] Confirm all speakers -- [ ] Test Zoom setup and recordings -- [ ] Prepare backup internet connection -- [ ] Set up registration system -- [ ] Create workshop repository -- [ ] Prepare slide deck -- [ ] Test all demos -- [ ] Set up Q&A system -- [ ] Prepare attendee welcome package - -### For Attendees - -- [ ] Register for workshop -- [ ] Install PanLL v0.2.0 -- [ ] Review prerequisites -- [ ] Test your setup -- [ ] Prepare questions -- [ ] Block calendar -- [ ] Join community - -## Post-Workshop Follow-up - -### Attendee Survey - -```markdown -# PanLL v0.2.0 Workshop Feedback - -Thank you for attending our workshop! We'd love your feedback. - -## Overall Experience - -😊 Very satisfied -😐 Satisfied -😕 Neutral -😟 Dissatisfied -😠 Very dissatisfied - -## Content Quality - -1. Relevance to your needs: ⭐️⭐️⭐️⭐️⭐️ -2. Depth of coverage: ⭐️⭐️⭐️⭐️⭐️ -3. Practical value: ⭐️⭐️⭐️⭐️⭐️ - -## Speaker Quality - -1. Clarity: ⭐️⭐️⭐️⭐️⭐️ -2. Knowledge: ⭐️⭐️⭐️⭐️⭐️ -3. Engagement: ⭐️⭐️⭐️⭐️⭐️ - -## What Was Most Valuable? - -- [ ] Identity management architecture -- [ ] Team collaboration patterns -- [ ] Automation techniques -- [ ] Extending PanLL -- [ ] Q&A session - -## What Could Be Improved? - -- [ ] More hands-on exercises -- [ ] Longer Q&A time -- [ ] More advanced topics -- [ ] Slower pace -- [ ] More beginner content - -## Additional Feedback - -[Open text field] - -## Would You Recommend? - -- [ ] Yes, absolutely -- [ ] Yes, with reservations -- [ ] Neutral -- [ ] No - -## Stay Connected - -- [ ] Join our mailing list -- [ ] Follow on GitHub -- [ ] Join community discussions -- [ ] Attend future events - -[Submit Feedback] -``` - -### Follow-up Email - -**Subject**: Thank You for Attending! + Workshop Resources - -**Body**: -``` -Hi [First Name], - -Thank you for attending our PanLL v0.2.0 Community Workshop! We hope you found it valuable. - -**Workshop Resources**: - -📚 **Slides**: [Download PDF](https://panll.hyperpolymath.dev/workshop/slides) -💻 **Code Samples**: [GitHub Repository](https://github.com/hyperpolymath/panll-workshop-june-2024) -📹 **Recording**: [Watch on YouTube](https://youtube.com/panll) (available in 48 hours) -📖 **Documentation**: [panll.hyperpolymath.dev/docs](https://panll.hyperpolymath.dev/docs) - -**Next Steps**: - -1. **Try It Out**: Apply what you learned to your PanLL setup -2. **Join the Community**: [GitHub Discussions](https://github.com/hyperpolymath/panll/discussions) -3. **Give Feedback**: [Survey Link] -4. **Stay Updated**: Follow us for future events - -**Upcoming Events**: - -📅 **Office Hours**: June 12, 14:00 UTC - - Q&A with the PanLL team - - [Register Here](https://panll.hyperpolymath.dev/office-hours) - -📅 **Plugin Contest**: June 15 - July 15 - - Build and submit your custom plugin - - Prizes for best submissions - - [Contest Details](https://panll.hyperpolymath.dev/plugin-contest) - -**Community Challenges**: - -1. **Best Plugin**: Submit your custom plugin by July 15 -2. **Performance**: Optimize snapshot operations -3. **UI Extension**: Create innovative custom components - -**Prizes**: -- 🥇 1st Place: PanLL Premium Support (6 months) -- 🥈 2nd Place: PanLL Swag Pack -- 🥉 3rd Place: Feature spotlight in blog - -We'd love your feedback! Please take 2 minutes to complete our survey: - -[👉 Take Survey](https://panll.hyperpolymath.dev/workshop-feedback) - -Thank you again for being part of our community! - -Best regards, -The PanLL Team -``` - -## Workshop Metrics - -### Success Metrics - -1. **Attendance**: Target 150-200 attendees -2. **Engagement**: 80%+ participation in Q&A -3. **Satisfaction**: 4.5/5 average rating -4. **Follow-up**: 30%+ survey response rate - -### Tracking - -```json -{ - "registrations": 187, - "attendees": 162, - "completion_rate": 0.87, - "questions_asked": 42, - "average_rating": 4.7, - "survey_responses": 58, - "follow_up_attendance": 38 -} -``` - -## Contingency Plans - -### Technical Issues - -1. **Zoom Failure**: - - Backup: YouTube Live stream - - Communication: Email + Discord announcement - - Recording: Local backup - -2. **Speaker Dropout**: - - Backup speakers ready - - Pre-recorded segments available - - Extended Q&A - -3. **Demo Failures**: - - Pre-recorded fallback demos - - Simplified alternative examples - - Focus on concepts - -### Low Attendance - -1. **Reschedule**: Offer alternative date -2. **Record**: Provide recording to registrants -3. **Content**: Repurpose as blog/tutorial - -### Time Management - -1. **Running Over**: Prioritize Q&A, move less critical content to follow-up -2. **Running Under**: Extended Q&A, additional demos, deeper dives - -## Workshop Repository Structure - -``` -panll-workshop-june-2024/ -├── README.md -├── agenda/ -│ ├── detailed.md -│ └── quick-reference.md -├── slides/ -│ ├── panll-workshop.pdf -│ └── panll-workshop.pptx -├── demos/ -│ ├── identity-management/ -│ ├── team-collaboration/ -│ ├── automation/ -│ └── extending/ -├── code-samples/ -│ ├── rust/ -│ ├── rescript/ -│ └── javascript/ -├── templates/ -│ ├── configuration.toml -│ └── plugin-template.rs -├── troubleshooting/ -│ └── guide.md -├── LICENSE -└── CONTRIBUTING.md -``` - -## Workshop FAQ - -### Registration - -**Q: Is the workshop really free?** -A: Yes! The workshop is completely free. We believe in open access to knowledge. - -**Q: Will the workshop be recorded?** -A: Yes, the recording will be available 48 hours after the workshop. - -**Q: Do I need to prepare anything?** -A: We recommend installing PanLL v0.2.0 and reviewing the blog post, but it's not required. - -### Technical - -**Q: What if I can't install PanLL v0.2.0?** -A: You can still attend! The concepts apply to all versions, and we'll provide guidance. - -**Q: Will the demos work on Windows/macOS?** -A: The workshop focuses on Linux, but concepts apply to all platforms. We'll note differences. - -**Q: What if I miss part of the workshop?** -A: The recording will be available, and we'll provide timestamps for each section. - -### Content - -**Q: Is this workshop for beginners or advanced users?** -A: The workshop covers advanced topics but explains concepts clearly. Basic PanLL knowledge is helpful but not required. - -**Q: Will you cover [specific topic]?** -A: Check the agenda above. If not listed, ask in the Q&A session! - -**Q: Can I ask questions during the workshop?** -A: Absolutely! We have dedicated Q&A time and will answer questions throughout. - -### After the Workshop - -**Q: How can I get the slides/code samples?** -A: Everything will be in the workshop repository: github.com/hyperpolymath/panll-workshop-june-2024 - -**Q: Will there be more workshops?** -A: Yes! We plan quarterly workshops. Follow us for announcements. - -**Q: How can I suggest topics for future workshops?** -A: Join our GitHub Discussions and post your ideas! - -## Workshop Promotion Timeline - -```mermaid -gantt - title Workshop Promotion Timeline - dateFormat YYYY-MM-DD - section Preparation - Finalize agenda :a1, 2024-05-01, 7d - Confirm speakers :a2, after a1, 3d - Create materials :a3, after a2, 10d - Test technical setup :a4, after a3, 3d - section Promotion - Announcement post :2024-05-10, 1d - Speaker highlights :2024-05-15, 1d - Countdown posts :2024-05-20, 7d - Email campaign :2024-05-22, 1d - Reminder emails :2024-06-03, 1d - Final reminder :2024-06-04, 1d - section Workshop - Workshop day :2024-06-05, 1d - section Follow-up - Send recording :2024-06-07, 1d - Send survey :2024-06-08, 1d - Office hours :2024-06-12, 1d -``` - -## Final Checklist - -### 1 Week Before - -- [ ] Finalize all content -- [ ] Test all demos -- [ ] Confirm all speakers -- [ ] Set up registration system -- [ ] Create workshop repository -- [ ] Schedule social media posts -- [ ] Prepare backup materials - -### 3 Days Before - -- [ ] Send reminder emails -- [ ] Post final countdown -- [ ] Test Zoom setup -- [ ] Prepare speaker briefing -- [ ] Set up Q&A system -- [ ] Prepare attendee guide - -### 1 Day Before - -- [ ] Final technical rehearsal -- [ ] Send final reminder -- [ ] Prepare backup internet -- [ ] Charge all equipment -- [ ] Set up monitoring -- [ ] Prepare welcome message - -### Workshop Day - -- [ ] Start early for setup -- [ ] Welcome attendees -- [ ] Monitor chat for questions -- [ ] Record session -- [ ] Manage time carefully -- [ ] Thank everyone - -### After Workshop - -- [ ] Upload recording -- [ ] Send thank-you emails -- [ ] Share resources -- [ ] Analyze feedback -- [ ] Plan next workshop - -## Conclusion - -This workshop plan provides a comprehensive structure for our PanLL v0.2.0 Community Workshop. With clear objectives, detailed content, and thorough preparation, we're set to deliver an engaging and valuable experience for our community. - -**Next Steps**: -1. Finalize workshop agenda -2. Confirm speaker availability -3. Create and test all demos -4. Set up registration system -5. Begin promotion campaign - -The workshop will establish PanLL v0.2.0 as the leading solution for collaborative workbench management and set the stage for our growing community. - -**Status**: Ready for finalization and execution 🚀 \ No newline at end of file