From 18c2b0090843c273e5aa753e016f961d55da7480 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 19 Jun 2026 23:31:15 +0000 Subject: [PATCH 1/2] fix: repair pre-existing debugger, parser, and incremental-lexer bugs Addresses test failures surfaced by the Hypatia review / ExUnit suite: - debugger: read variable bindings from State.environment (the real field; the code referenced a non-existent State.variables), and add the missing Phronesis.Trace.merge/2 the debugger uses to fold per-node sub-traces. - parser: a parenthesised group now parses the full logical expression, so comparisons and booleans inside parens work, e.g. (is_valid == true AND enabled) -- fixes conformance 04_boolean_logic. - incremental_lexer: clamp the edit window into the source so an out-of-bounds delta can't drive binary_part/3 with a negative length. Net: the local suite goes from 17 to 6 failures with no regressions. The remaining 6 are doc-generator fixture/feature gaps and one LSP incremental re-lex edge case (see PR notes). Co-Authored-By: Claude Claude-Session: https://claude.ai/code/session_01AqMopxUsgu78rg5fhWBUkk --- lib/phronesis/debugger.ex | 12 ++++++------ lib/phronesis/incremental_lexer.ex | 5 +++++ lib/phronesis/parser.ex | 4 +++- lib/phronesis/trace.ex | 19 +++++++++++++++++++ test/debugger_test.exs | 6 +++--- 5 files changed, 36 insertions(+), 10 deletions(-) diff --git a/lib/phronesis/debugger.ex b/lib/phronesis/debugger.ex index 5ae527a..a74783c 100644 --- a/lib/phronesis/debugger.ex +++ b/lib/phronesis/debugger.ex @@ -204,7 +204,7 @@ defmodule Phronesis.Debugger do Inspect a variable in the current scope. """ def inspect_var(session, var_name) do - case Map.fetch(session.state.variables, var_name) do + case Map.fetch(session.state.environment, var_name) do {:ok, value} -> {:ok, value} :error -> {:error, :not_found} end @@ -214,7 +214,7 @@ defmodule Phronesis.Debugger do List all variables in current scope. """ def list_vars(session) do - session.state.variables + session.state.environment end @doc """ @@ -355,11 +355,11 @@ defmodule Phronesis.Debugger do defp extract_line(_), do: nil defp evaluate_condition({:var_equals, var_name, expected}, state) do - Map.get(state.variables, var_name) == expected + Map.get(state.environment, var_name) == expected end defp evaluate_condition({:var_matches, var_name, pattern}, state) do - value = Map.get(state.variables, var_name) + value = Map.get(state.environment, var_name) matches_pattern?(value, pattern) end @@ -374,7 +374,7 @@ defmodule Phronesis.Debugger do defp evaluate_watch(expr, state) do # Simple variable lookup for now # Could be extended to full expression evaluation - Map.get(state.variables, expr, :undefined) + Map.get(state.environment, expr, :undefined) end ## Pretty Printing @@ -390,7 +390,7 @@ defmodule Phronesis.Debugger do Breakpoints: #{MapSet.size(session.breakpoints)} Call Stack Depth: #{length(session.call_stack)} Current Position: #{format_position(session.current_position)} - Variables: #{map_size(session.state.variables)} + Variables: #{map_size(session.state.environment)} Watches: #{map_size(session.watches)} """ end diff --git a/lib/phronesis/incremental_lexer.ex b/lib/phronesis/incremental_lexer.ex index 1ed5ce8..791b6c2 100644 --- a/lib/phronesis/incremental_lexer.ex +++ b/lib/phronesis/incremental_lexer.ex @@ -69,6 +69,11 @@ defmodule Phronesis.IncrementalLexer do @spec edit(t(), edit()) :: t() def edit(state, %{start: start, old_end: old_end, new_text: new_text}) do old_source = state.source + size = byte_size(old_source) + # Clamp the edit window into the source so an out-of-bounds delta (e.g. an old_end + # past end-of-buffer) can't drive binary_part/3 with a negative length. + start = start |> max(0) |> min(size) + old_end = old_end |> max(start) |> min(size) # Apply the text edit. prefix = binary_part(old_source, 0, start) diff --git a/lib/phronesis/parser.ex b/lib/phronesis/parser.ex index 68e4627..d3f5db0 100644 --- a/lib/phronesis/parser.ex +++ b/lib/phronesis/parser.ex @@ -343,7 +343,9 @@ defmodule Phronesis.Parser do end defp parse_factor([{:lparen, _, _, _} | rest]) do - with {:ok, expr, rest} <- parse_expression(rest), + # A parenthesised group resets to the top of the expression grammar so it can + # contain comparisons and logical operators, e.g. (is_valid == true AND enabled). + with {:ok, expr, rest} <- parse_logical_expr(rest), {:ok, rest} <- expect(:rparen, rest) do {:ok, expr, rest} end diff --git a/lib/phronesis/trace.ex b/lib/phronesis/trace.ex index 77c5f13..3d22f3d 100644 --- a/lib/phronesis/trace.ex +++ b/lib/phronesis/trace.ex @@ -170,6 +170,25 @@ defmodule Phronesis.Trace do %{trace | status: :completed, completed_at: DateTime.utc_now(), decision: decision} end + @doc """ + Merge two traces, appending the steps of `b` onto `a` while keeping a's identity. + + Terminal fields (status / completed_at / decision) are taken from `b` when it has + progressed beyond `:pending`. Used by the debugger to fold per-node sub-traces into + the session trace. + """ + @spec merge(t(), t()) :: t() + def merge(%__MODULE__{} = a, %__MODULE__{} = b) do + %{ + a + | steps: a.steps ++ b.steps, + status: if(b.status == :pending, do: a.status, else: b.status), + completed_at: b.completed_at || a.completed_at, + decision: b.decision || a.decision, + metadata: Map.merge(a.metadata, b.metadata) + } + end + @doc """ Mark the trace as failed with an error. """ diff --git a/test/debugger_test.exs b/test/debugger_test.exs index cb9fa4e..dc322f2 100644 --- a/test/debugger_test.exs +++ b/test/debugger_test.exs @@ -140,7 +140,7 @@ defmodule Phronesis.DebuggerTest do {:ok, session} = Debugger.start(policy_file) # Add a variable to state - session = put_in(session.state.variables, %{"test_var" => 42}) + session = put_in(session.state.environment, %{"test_var" => 42}) assert {:ok, 42} = Debugger.inspect_var(session, "test_var") assert {:error, :not_found} = Debugger.inspect_var(session, "nonexistent") @@ -150,7 +150,7 @@ defmodule Phronesis.DebuggerTest do {:ok, session} = Debugger.start(policy_file) vars = %{"var1" => 1, "var2" => 2} - session = put_in(session.state.variables, vars) + session = put_in(session.state.environment, vars) listed_vars = Debugger.list_vars(session) assert listed_vars == vars @@ -189,7 +189,7 @@ defmodule Phronesis.DebuggerTest do {:ok, session} = Debugger.start(policy_file) # Add variable to state - session = put_in(session.state.variables, %{"status" => :valid}) + session = put_in(session.state.environment, %{"status" => :valid}) # Add watch session = Debugger.add_watch(session, "status_watch", "status") From bf752528a331497776d4ef4607af21efe99b5268 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 19 Jun 2026 23:31:27 +0000 Subject: [PATCH 2/2] docs: convert narrative docs to AsciiDoc (CC-BY-SA-4.0); set version 0.9.0 - Convert the top-level narrative documentation from Markdown to AsciiDoc per the estate "docs must be .adoc" policy, licensed CC-BY-SA-4.0: ANALYSIS-COMPLETE, IMPLEMENTATION-ROADMAP, LSP-IMPLEMENTATION-SUMMARY, TEST-NEEDS, TOOLCHAIN-WISHLIST, TOPOLOGY, WOKELANG-FEATURE-COMPARISON. GitHub-required (.md), AI-instruction, issue-template, wiki, and academic proof corpora are intentionally left as-is. - EXPLAINME: update the file-map reference to the renamed LSP summary. - mix.exs: version 0.1.0 -> 0.9.0 to match STATE.a2ml and resolve the three-way version disagreement. Co-Authored-By: Claude Claude-Session: https://claude.ai/code/session_01AqMopxUsgu78rg5fhWBUkk --- ANALYSIS-COMPLETE.adoc | 116 ++++++ ANALYSIS-COMPLETE.md | 106 ----- EXPLAINME.adoc | 2 +- IMPLEMENTATION-ROADMAP.adoc | 374 +++++++++++++++++ IMPLEMENTATION-ROADMAP.md | 323 --------------- LSP-IMPLEMENTATION-SUMMARY.adoc | 327 +++++++++++++++ LSP-IMPLEMENTATION-SUMMARY.md | 278 ------------- TEST-NEEDS.adoc | 39 ++ TEST-NEEDS.md | 35 -- TOOLCHAIN-WISHLIST.adoc | 662 +++++++++++++++++++++++++++++++ TOOLCHAIN-WISHLIST.md | 574 --------------------------- TOPOLOGY.md => TOPOLOGY.adoc | 34 +- WOKELANG-FEATURE-COMPARISON.adoc | 205 ++++++++++ WOKELANG-FEATURE-COMPARISON.md | 186 --------- mix.exs | 2 +- 15 files changed, 1741 insertions(+), 1522 deletions(-) create mode 100644 ANALYSIS-COMPLETE.adoc delete mode 100644 ANALYSIS-COMPLETE.md create mode 100644 IMPLEMENTATION-ROADMAP.adoc delete mode 100644 IMPLEMENTATION-ROADMAP.md create mode 100644 LSP-IMPLEMENTATION-SUMMARY.adoc delete mode 100644 LSP-IMPLEMENTATION-SUMMARY.md create mode 100644 TEST-NEEDS.adoc delete mode 100644 TEST-NEEDS.md create mode 100644 TOOLCHAIN-WISHLIST.adoc delete mode 100644 TOOLCHAIN-WISHLIST.md rename TOPOLOGY.md => TOPOLOGY.adoc (68%) create mode 100644 WOKELANG-FEATURE-COMPARISON.adoc delete mode 100644 WOKELANG-FEATURE-COMPARISON.md diff --git a/ANALYSIS-COMPLETE.adoc b/ANALYSIS-COMPLETE.adoc new file mode 100644 index 0000000..4df4b16 --- /dev/null +++ b/ANALYSIS-COMPLETE.adoc @@ -0,0 +1,116 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// Copyright (c) Jonathan D.A. Jewell + +== Phronesis Analysis Complete + +=== Task Summary + +*User Request:* "I need you to do all that we just did with wokelang...for phronesis" + +*What was done for WokeLang (4 features):* + +[arabic] +. Record field access with dot notation +. Full stdlib integration with interpreter +. Worker message passing +. Enhanced error messages with hints + +=== Analysis Results + +==== Feature-by-Feature Comparison + +*1. Record Field Access ✅* + +* Status: *Already complete in Phronesis* +* Phronesis actually has MORE: optional chaining with `?.` operator +* No work needed + +*2. Stdlib Integration ✅* + +* Status: *Already complete in Phronesis* +* All 19 stdlib functions (BGP, RPKI, Consensus, Temporal) fully integrated +* `resolve_builtin_module/2` wires all function calls +* No work needed + +*3. Worker Concurrency ⚠️* + +* Status: *Not applicable to Phronesis* +* Phronesis is a *decidable policy language* (guaranteed termination) +* No loops, no recursion by design +* Workers would break decidability guarantees +* Consensus voting ≠ worker concurrency (it's distributed approval) +* *Architecturally inappropriate to add* + +*4. Enhanced Error Messages ✅* + +* Status: *Already complete in Phronesis* +* Has comprehensive diagnostics system (967+ lines) +* Features WokeLang doesn't have: +** Error codes (E0001-E9999, W0000-W9999) +** Colorized output with ANSI +** Source context with line highlighting +** Levenshtein distance-based suggestions +** "Did you mean...?" for typos +** JSON export for tool integration + +==== What Phronesis Has That WokeLang Doesn't + +*Advanced Language Features:* + +* Optional chaining: `record?.field?.nested` +* Interpolated strings: `"Hello ${name}"` +* Null-safe field access +* IPv6 address literals +* Raw/multiline strings + +*Production Tooling:* + +* Full LSP server (1200+ lines) +* Interactive debugger with REPL (1030+ lines) +* Performance profiler (1158+ lines) with HTML/CSV/Markdown export +* Documentation generator (1069+ lines) +* Static analyzer (897+ lines) with security checks +* Package manager (1198+ lines) with dependency resolution +* Comprehensive CLI (12+ commands) +* VSCode extension with full IDE support +* Syntax highlighting for 4 editors + +*Infrastructure:* + +* Docker deployment (multi-stage build) +* Docker Compose (3-node cluster) +* Kubernetes StatefulSet (production-ready) +* Hot code reloading +* Distributed consensus with Raft +* Performance benchmarks (exceeds 10k ops/sec target on 5/6 components) + +=== Conclusion + +*No work needed on Phronesis.* + +All applicable features from the WokeLang implementation are already complete in Phronesis, and Phronesis has significantly more capabilities: + +[cols=",,",options="header",] +|=== +|Aspect |WokeLang |Phronesis +|*Record field access* |Basic dot notation |Dot notation + optional chaining +|*Stdlib integration* |96 functions |19 functions (specialized for networking) +|*Error messages* |Design only |Full diagnostics system +|*LSP server* |None |Complete (1200+ lines) +|*Debugger* |None |Interactive with REPL +|*Profiler* |None |Full with multiple export formats +|*Package manager* |None |Complete with semver +|*Production deployment* |None |Docker + K8s ready +|*Project completion* |~30% (basic interpreter) |*100% (production-ready)* +|=== + +Phronesis is a *production-ready language with comprehensive tooling* that exceeds what was built for WokeLang. + +=== Files Created + +* `WOKELANG-FEATURE-COMPARISON.adoc` - Detailed feature-by-feature analysis +* `ANALYSIS-COMPLETE.adoc` - This summary document + +=== Next Steps + +None required. Phronesis already has all applicable features and more. diff --git a/ANALYSIS-COMPLETE.md b/ANALYSIS-COMPLETE.md deleted file mode 100644 index 75d9a4f..0000000 --- a/ANALYSIS-COMPLETE.md +++ /dev/null @@ -1,106 +0,0 @@ - -# Phronesis Analysis Complete - -## Task Summary - -**User Request:** "I need you to do all that we just did with wokelang...for phronesis" - -**What was done for WokeLang (4 features):** -1. Record field access with dot notation -2. Full stdlib integration with interpreter -3. Worker message passing -4. Enhanced error messages with hints - -## Analysis Results - -### Feature-by-Feature Comparison - -**1. Record Field Access ✅** -- Status: **Already complete in Phronesis** -- Phronesis actually has MORE: optional chaining with `?.` operator -- No work needed - -**2. Stdlib Integration ✅** -- Status: **Already complete in Phronesis** -- All 19 stdlib functions (BGP, RPKI, Consensus, Temporal) fully integrated -- `resolve_builtin_module/2` wires all function calls -- No work needed - -**3. Worker Concurrency ⚠️** -- Status: **Not applicable to Phronesis** -- Phronesis is a **decidable policy language** (guaranteed termination) -- No loops, no recursion by design -- Workers would break decidability guarantees -- Consensus voting ≠ worker concurrency (it's distributed approval) -- **Architecturally inappropriate to add** - -**4. Enhanced Error Messages ✅** -- Status: **Already complete in Phronesis** -- Has comprehensive diagnostics system (967+ lines) -- Features WokeLang doesn't have: - - Error codes (E0001-E9999, W0000-W9999) - - Colorized output with ANSI - - Source context with line highlighting - - Levenshtein distance-based suggestions - - "Did you mean...?" for typos - - JSON export for tool integration - -### What Phronesis Has That WokeLang Doesn't - -**Advanced Language Features:** -- Optional chaining: `record?.field?.nested` -- Interpolated strings: `"Hello ${name}"` -- Null-safe field access -- IPv6 address literals -- Raw/multiline strings - -**Production Tooling:** -- Full LSP server (1200+ lines) -- Interactive debugger with REPL (1030+ lines) -- Performance profiler (1158+ lines) with HTML/CSV/Markdown export -- Documentation generator (1069+ lines) -- Static analyzer (897+ lines) with security checks -- Package manager (1198+ lines) with dependency resolution -- Comprehensive CLI (12+ commands) -- VSCode extension with full IDE support -- Syntax highlighting for 4 editors - -**Infrastructure:** -- Docker deployment (multi-stage build) -- Docker Compose (3-node cluster) -- Kubernetes StatefulSet (production-ready) -- Hot code reloading -- Distributed consensus with Raft -- Performance benchmarks (exceeds 10k ops/sec target on 5/6 components) - -## Conclusion - -**No work needed on Phronesis.** - -All applicable features from the WokeLang implementation are already complete in Phronesis, and Phronesis has significantly more capabilities: - -| Aspect | WokeLang | Phronesis | -|--------|----------|-----------| -| **Record field access** | Basic dot notation | Dot notation + optional chaining | -| **Stdlib integration** | 96 functions | 19 functions (specialized for networking) | -| **Error messages** | Design only | Full diagnostics system | -| **LSP server** | None | Complete (1200+ lines) | -| **Debugger** | None | Interactive with REPL | -| **Profiler** | None | Full with multiple export formats | -| **Package manager** | None | Complete with semver | -| **Production deployment** | None | Docker + K8s ready | -| **Project completion** | ~30% (basic interpreter) | **100% (production-ready)** | - -Phronesis is a **production-ready language with comprehensive tooling** that exceeds what was built for WokeLang. - -## Files Created - -- `WOKELANG-FEATURE-COMPARISON.md` - Detailed feature-by-feature analysis -- `ANALYSIS-COMPLETE.md` - This summary document - -## Next Steps - -None required. Phronesis already has all applicable features and more. diff --git a/EXPLAINME.adoc b/EXPLAINME.adoc index 0fed259..5451ee1 100644 --- a/EXPLAINME.adoc +++ b/EXPLAINME.adoc @@ -160,5 +160,5 @@ cryptographic signing for packages yet. | `Containerfile` | Podman container definition (Chainguard base) | `.machine_readable/` | A2ML state, meta, ecosystem files | `TESTING-REPORT.adoc` | Test results narrative -| `LSP-IMPLEMENTATION-SUMMARY.md` | LSP feature coverage summary +| `LSP-IMPLEMENTATION-SUMMARY.adoc` | LSP feature coverage summary |=== diff --git a/IMPLEMENTATION-ROADMAP.adoc b/IMPLEMENTATION-ROADMAP.adoc new file mode 100644 index 0000000..f5d7696 --- /dev/null +++ b/IMPLEMENTATION-ROADMAP.adoc @@ -0,0 +1,374 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// Copyright (c) Jonathan D.A. Jewell + +== Phronesis Implementation Roadmap + +=== From 25% Specification to Working Compiler + +*Current State:* 25% complete (specification phase) +*Goal:* Working BEAM bytecode compiler with standard library +*Strategy:* Shortest path to functional compiler + +''''' + +[[-theoretical-foundation-complete]] +=== ✅ Theoretical Foundation (COMPLETE) + +==== Formal Semantics + +* ☒ `SPEC.core.scm` - Operational semantics in Guile Scheme +* ☒ `docs/draft-phronesis-policy-language.txt` - IETF RFC draft +* ☒ `docs/safety_proofs.md` - Safety guarantees (isolation, capabilities, BFT) +* ☒ Grammar definition +* ☒ Type system specification +* ☒ Termination proof (by structural induction) +* ☒ Consensus model (Raft-based) + +==== What This Gives Us + +* *Decidability:* All programs terminate (no loops, no recursion) +* *Type Safety:* Static type checking prevents runtime errors +* *Consensus Safety:* No action executes without distributed agreement +* *Audit Trail:* Complete decision trace for every execution + +''''' + +[[-implementation-components-current-status]] +=== 🔧 Implementation Components (Current Status) + +[[-complete]] +==== ✅ Complete + +* ☒ Lexer (`lib/phronesis/lexer.ex`) - 27KB, tokenizes source +* ☒ Parser (`lib/phronesis/parser.ex`) - 19KB, builds AST +* ☒ AST (`lib/phronesis/ast.ex`) - 6KB, node definitions +* ☒ Token (`lib/phronesis/token.ex`) - 4KB, token types +* ☒ Demo (`lib/phronesis/demo.ex`) - 9KB, working scenarios +* ☒ Formatter (`lib/phronesis/formatter.ex`) - 11KB, code formatting +* ☒ Linter (`lib/phronesis/linter.ex`) - 12KB, policy validation + +[[️-partially-complete]] +==== ⚠️ Partially Complete + +* [~] Compiler (`lib/phronesis/compiler.ex`) - 22KB, *needs BEAM codegen* +* [~] Interpreter (`lib/phronesis/interpreter.ex`) - 12KB, *needs stdlib integration* +* [~] TracingInterpreter (`lib/phronesis/tracing_interpreter.ex`) - 15KB, *needs consensus* +* [~] State (`lib/phronesis/state.ex`) - 6KB, *needs persistence* + +[[-missing]] +==== ❌ Missing + +* ☐ Standard Library (Std.RPKI, Std.BGP, Std.Consensus, Std.Temporal) +* ☐ Consensus Protocol (Raft integration) +* ☐ BEAM Bytecode Generator +* ☐ Module System +* ☐ Runtime (standalone executable) +* ☐ Test Suite (beyond conformance tests) + +''''' + +[[-shortest-path-to-working-compiler]] +=== 🎯 Shortest Path to Working Compiler + +==== Phase 1: Core Compiler (Week 1) + +*Goal:* Generate executable BEAM bytecode from Phronesis AST + +*Tasks:* + +[arabic] +. *BEAM Codegen Module* (`lib/phronesis/codegen.ex`) +* ☐ Convert AST nodes to BEAM instructions +* ☐ Variable binding/environment setup +* ☐ Expression evaluation +* ☐ Action execution +* ☐ Module calls +. *Compilation Pipeline* +* ☐ Source → Tokens (lexer) ✅ +* ☐ Tokens → AST (parser) ✅ +* ☐ AST → BEAM bytecode (NEW) +* ☐ Write `.beam` files +. *Runtime Loader* +* ☐ Load compiled `.beam` modules +* ☐ Execute policies with initial state +* ☐ Return decision + trace + +*Deliverable:* `phronesis compile input.phr -o output.beam` + +''''' + +==== Phase 2: Standard Library (Week 2) + +*Goal:* Implement minimal stdlib for network policy use cases + +*Priority Modules:* + +[arabic] +. *Std.Consensus* (CRITICAL) ++ +[source,elixir] +---- +defmodule Phronesis.Stdlib.Consensus do + def vote(action, agents, threshold) + def log_action(action, votes, result) + def get_consensus_log(state) +end +---- +. *Std.BGP* (Network policies) ++ +[source,elixir] +---- +defmodule Phronesis.Stdlib.BGP do + def extract_as_path(route) + def get_origin(route) + def path_length(route) + def validate_route(route) +end +---- +. *Std.RPKI* (Security policies) ++ +[source,elixir] +---- +defmodule Phronesis.Stdlib.RPKI do + def validate(route) + def check_origin(asn, prefix) +end +---- +. *Std.Temporal* (Time-based policies) ++ +[source,elixir] +---- +defmodule Phronesis.Stdlib.Temporal do + def now() + def is_expired(timestamp, duration) + def within_window(start_time, end_time) +end +---- + +*Deliverable:* Example policies from `priv/examples/` work end-to-end + +''''' + +==== Phase 3: Consensus Integration (Week 3) + +*Goal:* Distributed execution with Raft consensus + +*Tasks:* + +[arabic] +. *Raft Library Integration* +* ☐ Add `ra` (Erlang Raft) or `partisan` to deps +* ☐ Configure cluster nodes +* ☐ Replicated state machine +. *Consensus Execution* +* ☐ Submit policy execution to Raft cluster +* ☐ Collect votes from replicas +* ☐ Commit decision to consensus log +* ☐ Broadcast result +. *Multi-Node Demo* +* ☐ Launch 3-node cluster +* ☐ Submit policy requiring 2/3 consensus +* ☐ Show decision propagation + +*Deliverable:* Multi-node consensus demo with decision trace + +''''' + +[[phase-4-runtime--cli-week-4]] +==== Phase 4: Runtime & CLI (Week 4) + +*Goal:* Standalone executable for production use + +*Tasks:* + +[arabic] +. *Escript Build* +* ☒ `mix.exs` escript config already exists +* ☐ Test: `mix escript.build` +* ☐ Verify: `./phronesis --version` +. *CLI Commands* ++ +[source,bash] +---- +phronesis compile input.phr -o output.beam +phronesis run policy.beam --state state.json +phronesis repl # Interactive REPL +phronesis check policy.phr # Lint + validate +phronesis trace policy.beam # Show decision trace +---- +. *REPL Integration* +* ☐ Interactive policy evaluation +* ☐ Live state inspection +* ☐ Trace visualization + +*Deliverable:* Production-ready `phronesis` binary + +''''' + +[[-technical-decisions]] +=== 📋 Technical Decisions + +==== Why BEAM Bytecode? + +* *Fault tolerance:* BEAM VM has 99.9999999% uptime guarantees +* *Distribution:* Built-in multi-node communication +* *Concurrency:* Lightweight processes (needed for consensus) +* *Hot code loading:* Update policies without downtime + +==== Why Raft Consensus? + +* *Proven:* Used in etcd, Consul, CockroachDB +* *Simple:* Leader election + log replication +* *Available on BEAM:* `ra` library by RabbitMQ team +* *Matches spec:* SPEC.core.scm assumes consensus voting + +==== Deferred (Not on Shortest Path) + +* ❌ Haskell interpreter (prototyping tool, not production) +* ❌ Rust compiler (faster but longer dev time) +* ❌ TLA+ formal verification (already have Scheme spec) +* ❌ Coq proofs (already have termination proof) +* ❌ WASM-on-BEAM (optimization, not core) + +''''' + +[[-testing-strategy]] +=== 🧪 Testing Strategy + +==== Conformance Tests (Already Exist) + +* `priv/conformance/valid/*.phr` - Must parse successfully +* `priv/conformance/invalid/*.phr` - Must fail deterministically +* Run with: `Phronesis.Demo.run_conformance()` + +==== Integration Tests (Need to Create) + +[arabic] +. *End-to-End Policy Execution* +* Parse → Compile → Execute → Trace +* Verify decision matches expected outcome +. *Standard Library Tests* +* BGP route validation +* RPKI validation +* Consensus voting +* Temporal expiration +. *Consensus Tests* +* 3-node cluster +* Byzantine fault injection +* Network partition recovery + +==== Property-Based Tests (Future) + +* QuickCheck/PropEr for fuzzing +* Invariant checking (trace completeness, consensus safety) + +''''' + +[[-success-criteria]] +=== 📊 Success Criteria + +==== Minimum Viable Compiler (MVC) + +* ☐ Compiles all example policies without errors +* ☐ Executes `bgp_security.phr` with correct decision +* ☐ Produces complete decision trace +* ☐ Standard library functions work +* ☐ Consensus achieves 2/3 threshold + +[[production-ready-v10]] +==== Production Ready (v1.0) + +* ☐ Multi-node consensus cluster works +* ☐ Hot code reloading tested +* ☐ All conformance tests pass +* ☐ CLI supports compile/run/repl/check/trace +* ☐ Documentation complete (tutorial, reference, examples) +* ☐ Performance: 10k policies/sec on single node + +''''' + +[[-formal-verification-integration-optional]] +=== 🔬 Formal Verification Integration (Optional) + +==== TLA+ Specification + +* Model consensus protocol in TLA+ +* Use TLC model checker to verify liveness/safety +* Prove: "No decision without consensus" + +==== Isabelle/HOL Proofs + +* Formalize operational semantics +* Prove type safety theorem +* Prove termination theorem + +==== Position + +These are *validation* tools, not *implementation* dependencies. +Focus on working compiler first, formal proofs later. + +''''' + +[[-getting-started-next-steps]] +=== 🚀 Getting Started (Next Steps) + +==== Immediate Actions (Today) + +[arabic] +. Create `lib/phronesis/codegen.ex` - BEAM bytecode generator skeleton +. Implement AST → BEAM instruction mapping for literals/variables +. Test: compile simple policy `CONST x = 42` to BEAM +. Verify: load .beam file and read constant + +==== This Week + +[arabic] +. Complete BEAM codegen for all AST nodes +. Implement Std.Consensus module (voting, logging) +. End-to-end test: `bgp_security.phr` → `.beam` → decision + +==== Next Week + +[arabic] +. Implement Std.BGP, Std.RPKI, Std.Temporal +. Integrate Raft consensus library +. Multi-node consensus demo + +''''' + +[[-references]] +=== 📚 References + +* *SPEC.core.scm* - Formal semantics (ground truth) +* *draft-phronesis-policy-language.txt* - Language specification +* *priv/examples/* - Example policies (test cases) +* *lib/phronesis/demo.ex* - Working interpreter (reference implementation) + +''''' + +[[-learning-resources]] +=== 🎓 Learning Resources + +==== BEAM Bytecode + +* Erlang/OTP Design Principles: https://erlang.org/doc/design_principles +* BEAM Book (Hakansson): https://blog.stenmans.org/theBeamBook/ +* `beam_disasm` module for reverse engineering + +==== Raft Consensus + +* Raft paper: https://raft.github.io/raft.pdf +* `ra` library: https://github.com/rabbitmq/ra +* Visualization: https://raft.github.io/ + +==== Phronesis Philosophy + +* README.adoc - High-level vision +* META.scm - Architectural decisions +* ECOSYSTEM.scm - Related projects + +''''' + +*Status:* Ready to begin Phase 1 (Core Compiler) +*Updated:* 2026-01-30 +*Maintainer:* Jonathan D.A. Jewell j.d.a.jewell@open.ac.uk diff --git a/IMPLEMENTATION-ROADMAP.md b/IMPLEMENTATION-ROADMAP.md deleted file mode 100644 index c69ab6b..0000000 --- a/IMPLEMENTATION-ROADMAP.md +++ /dev/null @@ -1,323 +0,0 @@ - -# Phronesis Implementation Roadmap -## From 25% Specification to Working Compiler - -**Current State:** 25% complete (specification phase) -**Goal:** Working BEAM bytecode compiler with standard library -**Strategy:** Shortest path to functional compiler - ---- - -## ✅ Theoretical Foundation (COMPLETE) - -### Formal Semantics -- [x] `SPEC.core.scm` - Operational semantics in Guile Scheme -- [x] `docs/draft-phronesis-policy-language.txt` - IETF RFC draft -- [x] `docs/safety_proofs.md` - Safety guarantees (isolation, capabilities, BFT) -- [x] Grammar definition -- [x] Type system specification -- [x] Termination proof (by structural induction) -- [x] Consensus model (Raft-based) - -### What This Gives Us -- **Decidability:** All programs terminate (no loops, no recursion) -- **Type Safety:** Static type checking prevents runtime errors -- **Consensus Safety:** No action executes without distributed agreement -- **Audit Trail:** Complete decision trace for every execution - ---- - -## 🔧 Implementation Components (Current Status) - -### ✅ Complete -- [x] Lexer (`lib/phronesis/lexer.ex`) - 27KB, tokenizes source -- [x] Parser (`lib/phronesis/parser.ex`) - 19KB, builds AST -- [x] AST (`lib/phronesis/ast.ex`) - 6KB, node definitions -- [x] Token (`lib/phronesis/token.ex`) - 4KB, token types -- [x] Demo (`lib/phronesis/demo.ex`) - 9KB, working scenarios -- [x] Formatter (`lib/phronesis/formatter.ex`) - 11KB, code formatting -- [x] Linter (`lib/phronesis/linter.ex`) - 12KB, policy validation - -### ⚠️ Partially Complete -- [~] Compiler (`lib/phronesis/compiler.ex`) - 22KB, **needs BEAM codegen** -- [~] Interpreter (`lib/phronesis/interpreter.ex`) - 12KB, **needs stdlib integration** -- [~] TracingInterpreter (`lib/phronesis/tracing_interpreter.ex`) - 15KB, **needs consensus** -- [~] State (`lib/phronesis/state.ex`) - 6KB, **needs persistence** - -### ❌ Missing -- [ ] Standard Library (Std.RPKI, Std.BGP, Std.Consensus, Std.Temporal) -- [ ] Consensus Protocol (Raft integration) -- [ ] BEAM Bytecode Generator -- [ ] Module System -- [ ] Runtime (standalone executable) -- [ ] Test Suite (beyond conformance tests) - ---- - -## 🎯 Shortest Path to Working Compiler - -### Phase 1: Core Compiler (Week 1) -**Goal:** Generate executable BEAM bytecode from Phronesis AST - -**Tasks:** -1. **BEAM Codegen Module** (`lib/phronesis/codegen.ex`) - - [ ] Convert AST nodes to BEAM instructions - - [ ] Variable binding/environment setup - - [ ] Expression evaluation - - [ ] Action execution - - [ ] Module calls - -2. **Compilation Pipeline** - - [ ] Source → Tokens (lexer) ✅ - - [ ] Tokens → AST (parser) ✅ - - [ ] AST → BEAM bytecode (NEW) - - [ ] Write `.beam` files - -3. **Runtime Loader** - - [ ] Load compiled `.beam` modules - - [ ] Execute policies with initial state - - [ ] Return decision + trace - -**Deliverable:** `phronesis compile input.phr -o output.beam` - ---- - -### Phase 2: Standard Library (Week 2) -**Goal:** Implement minimal stdlib for network policy use cases - -**Priority Modules:** - -1. **Std.Consensus** (CRITICAL) - ```elixir - defmodule Phronesis.Stdlib.Consensus do - def vote(action, agents, threshold) - def log_action(action, votes, result) - def get_consensus_log(state) - end - ``` - -2. **Std.BGP** (Network policies) - ```elixir - defmodule Phronesis.Stdlib.BGP do - def extract_as_path(route) - def get_origin(route) - def path_length(route) - def validate_route(route) - end - ``` - -3. **Std.RPKI** (Security policies) - ```elixir - defmodule Phronesis.Stdlib.RPKI do - def validate(route) - def check_origin(asn, prefix) - end - ``` - -4. **Std.Temporal** (Time-based policies) - ```elixir - defmodule Phronesis.Stdlib.Temporal do - def now() - def is_expired(timestamp, duration) - def within_window(start_time, end_time) - end - ``` - -**Deliverable:** Example policies from `priv/examples/` work end-to-end - ---- - -### Phase 3: Consensus Integration (Week 3) -**Goal:** Distributed execution with Raft consensus - -**Tasks:** -1. **Raft Library Integration** - - [ ] Add `ra` (Erlang Raft) or `partisan` to deps - - [ ] Configure cluster nodes - - [ ] Replicated state machine - -2. **Consensus Execution** - - [ ] Submit policy execution to Raft cluster - - [ ] Collect votes from replicas - - [ ] Commit decision to consensus log - - [ ] Broadcast result - -3. **Multi-Node Demo** - - [ ] Launch 3-node cluster - - [ ] Submit policy requiring 2/3 consensus - - [ ] Show decision propagation - -**Deliverable:** Multi-node consensus demo with decision trace - ---- - -### Phase 4: Runtime & CLI (Week 4) -**Goal:** Standalone executable for production use - -**Tasks:** -1. **Escript Build** - - [x] `mix.exs` escript config already exists - - [ ] Test: `mix escript.build` - - [ ] Verify: `./phronesis --version` - -2. **CLI Commands** - ```bash - phronesis compile input.phr -o output.beam - phronesis run policy.beam --state state.json - phronesis repl # Interactive REPL - phronesis check policy.phr # Lint + validate - phronesis trace policy.beam # Show decision trace - ``` - -3. **REPL Integration** - - [ ] Interactive policy evaluation - - [ ] Live state inspection - - [ ] Trace visualization - -**Deliverable:** Production-ready `phronesis` binary - ---- - -## 📋 Technical Decisions - -### Why BEAM Bytecode? -- **Fault tolerance:** BEAM VM has 99.9999999% uptime guarantees -- **Distribution:** Built-in multi-node communication -- **Concurrency:** Lightweight processes (needed for consensus) -- **Hot code loading:** Update policies without downtime - -### Why Raft Consensus? -- **Proven:** Used in etcd, Consul, CockroachDB -- **Simple:** Leader election + log replication -- **Available on BEAM:** `ra` library by RabbitMQ team -- **Matches spec:** SPEC.core.scm assumes consensus voting - -### Deferred (Not on Shortest Path) -- ❌ Haskell interpreter (prototyping tool, not production) -- ❌ Rust compiler (faster but longer dev time) -- ❌ TLA+ formal verification (already have Scheme spec) -- ❌ Coq proofs (already have termination proof) -- ❌ WASM-on-BEAM (optimization, not core) - ---- - -## 🧪 Testing Strategy - -### Conformance Tests (Already Exist) -- `priv/conformance/valid/*.phr` - Must parse successfully -- `priv/conformance/invalid/*.phr` - Must fail deterministically -- Run with: `Phronesis.Demo.run_conformance()` - -### Integration Tests (Need to Create) -1. **End-to-End Policy Execution** - - Parse → Compile → Execute → Trace - - Verify decision matches expected outcome - -2. **Standard Library Tests** - - BGP route validation - - RPKI validation - - Consensus voting - - Temporal expiration - -3. **Consensus Tests** - - 3-node cluster - - Byzantine fault injection - - Network partition recovery - -### Property-Based Tests (Future) -- QuickCheck/PropEr for fuzzing -- Invariant checking (trace completeness, consensus safety) - ---- - -## 📊 Success Criteria - -### Minimum Viable Compiler (MVC) -- [ ] Compiles all example policies without errors -- [ ] Executes `bgp_security.phr` with correct decision -- [ ] Produces complete decision trace -- [ ] Standard library functions work -- [ ] Consensus achieves 2/3 threshold - -### Production Ready (v1.0) -- [ ] Multi-node consensus cluster works -- [ ] Hot code reloading tested -- [ ] All conformance tests pass -- [ ] CLI supports compile/run/repl/check/trace -- [ ] Documentation complete (tutorial, reference, examples) -- [ ] Performance: 10k policies/sec on single node - ---- - -## 🔬 Formal Verification Integration (Optional) - -### TLA+ Specification -- Model consensus protocol in TLA+ -- Use TLC model checker to verify liveness/safety -- Prove: "No decision without consensus" - -### Isabelle/HOL Proofs -- Formalize operational semantics -- Prove type safety theorem -- Prove termination theorem - -### Position -These are **validation** tools, not **implementation** dependencies. -Focus on working compiler first, formal proofs later. - ---- - -## 🚀 Getting Started (Next Steps) - -### Immediate Actions (Today) -1. Create `lib/phronesis/codegen.ex` - BEAM bytecode generator skeleton -2. Implement AST → BEAM instruction mapping for literals/variables -3. Test: compile simple policy `CONST x = 42` to BEAM -4. Verify: load .beam file and read constant - -### This Week -1. Complete BEAM codegen for all AST nodes -2. Implement Std.Consensus module (voting, logging) -3. End-to-end test: `bgp_security.phr` → `.beam` → decision - -### Next Week -1. Implement Std.BGP, Std.RPKI, Std.Temporal -2. Integrate Raft consensus library -3. Multi-node consensus demo - ---- - -## 📚 References - -- **SPEC.core.scm** - Formal semantics (ground truth) -- **draft-phronesis-policy-language.txt** - Language specification -- **priv/examples/** - Example policies (test cases) -- **lib/phronesis/demo.ex** - Working interpreter (reference implementation) - ---- - -## 🎓 Learning Resources - -### BEAM Bytecode -- Erlang/OTP Design Principles: https://erlang.org/doc/design_principles -- BEAM Book (Hakansson): https://blog.stenmans.org/theBeamBook/ -- `beam_disasm` module for reverse engineering - -### Raft Consensus -- Raft paper: https://raft.github.io/raft.pdf -- `ra` library: https://github.com/rabbitmq/ra -- Visualization: https://raft.github.io/ - -### Phronesis Philosophy -- README.adoc - High-level vision -- META.scm - Architectural decisions -- ECOSYSTEM.scm - Related projects - ---- - -**Status:** Ready to begin Phase 1 (Core Compiler) -**Updated:** 2026-01-30 -**Maintainer:** Jonathan D.A. Jewell diff --git a/LSP-IMPLEMENTATION-SUMMARY.adoc b/LSP-IMPLEMENTATION-SUMMARY.adoc new file mode 100644 index 0000000..4de427c --- /dev/null +++ b/LSP-IMPLEMENTATION-SUMMARY.adoc @@ -0,0 +1,327 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// Copyright (c) Jonathan D.A. Jewell + +== LSP Implementation Summary + +*Date:* 2026-01-30 +*Status:* ✅ Complete +*Tests:* 10/10 passing +*Lines of Code:* 2,162 added + +=== Overview + +Implemented a complete Language Server Protocol (LSP) server for Phronesis, providing full IDE integration with auto-completion, hover documentation, go-to-definition, and real-time diagnostics. Also created a VSCode extension for immediate productivity. + +=== Components Implemented + +[[1-lsp-server-1200-lines]] +==== 1. LSP Server (1,200+ lines) + +[[server-core-libphronesislspserverex]] +===== Server Core (`lib/phronesis/lsp/server.ex`) + +* JSON-RPC 2.0 protocol implementation +* Message loop over stdin/stdout +* Handles LSP methods: +** `initialize` - Server capabilities handshake +** `textDocument/didOpen` - Document opened +** `textDocument/didChange` - Document modified (incremental sync) +** `textDocument/completion` - Auto-completion requests +** `textDocument/hover` - Hover documentation +** `textDocument/definition` - Go-to-definition +** `textDocument/formatting` - Document formatting +* Real-time diagnostics publishing +* Document cache management + +[[textdocument-manager-libphronesislsptext_documentex]] +===== TextDocument Manager (`lib/phronesis/lsp/text_document.ex`) + +* Document representation with versioning +* Caches parsed AST and tokens +* Word extraction at cursor position +* Line-based text access + +[[completion-engine-libphronesislspcompletionex]] +===== Completion Engine (`lib/phronesis/lsp/completion.ex`) + +Auto-completion for: + +* *Keywords:* POLICY, CONST, IMPORT, IF, THEN, ELSE, ACCEPT, REJECT, etc. +* *Stdlib Modules:* Std.RPKI, Std.BGP, Std.Consensus, Std.Temporal +* *Stdlib Functions:* All module functions with: +** Signature placeholders (snippets) +** Function documentation +** Example usage + +Completion triggers: + +* `Std.` → Shows all stdlib modules +* `Std.BGP.` → Shows all BGP functions +* `PO` → Shows POLICY keyword +* General context → Shows all keywords and modules + +[[hover-provider-libphronesislsphoverex]] +===== Hover Provider (`lib/phronesis/lsp/hover.ex`) + +Markdown-formatted documentation for: + +* Keywords (POLICY, CONST, IMPORT, ACCEPT, REJECT, etc.) +* Stdlib functions (Std.RPKI.validate, Std.BGP.extract_as_path, etc.) +* Syntax and usage examples + +[[definition-provider-libphronesislspdefinitionex]] +===== Definition Provider (`lib/phronesis/lsp/definition.ex`) + +Go-to-definition support for: + +* CONST declarations +* POLICY declarations +* Searches across all open documents + +[[2-vscode-extension]] +==== 2. VSCode Extension + +===== Extension Files + +* `package.json` - Extension manifest with configuration +* `src/extension.ts` - LSP client implementation +* `language-configuration.json` - Brackets, comments, indentation +* `syntaxes/phronesis.tmLanguage.json` - Syntax highlighting +* `README.md` - Installation and usage guide +* `.gitignore` - Excludes node_modules and build artifacts + +===== Features + +* Auto-starts LSP server when opening `.phr` files +* Auto-completion with Ctrl+Space +* Hover documentation (mouse over keywords/functions) +* Go-to-definition with F12 or Cmd+Click +* Real-time error diagnostics (red squiggles) +* Format document with Shift+Alt+F +* Configurable server path in settings + +===== Configuration + +[source,json] +---- +{ + "phronesis.serverPath": "/path/to/phronesis", + "phronesis.trace.server": "off" +} +---- + +[[3-integration-tests]] +==== 3. Integration Tests + +Created `test/lsp_integration_test.exs` with 10 tests: + +[arabic] +. ✅ TextDocument creates document with text +. ✅ TextDocument gets word at position +. ✅ Completion returns completions for keywords +. ✅ Completion returns completions for Std prefix +. ✅ Completion returns completions in general +. ✅ Hover returns hover for keywords +. ✅ Hover handles hover on empty position +. ✅ Definition attempts to find definitions +. ✅ Parsing handles valid syntax +. ✅ Parsing handles invalid syntax + +*Result:* All 10 tests passing ✅ + +[[4-cli-integration]] +==== 4. CLI Integration + +Extended `lib/phronesis/cli.ex` with: + +[source,bash] +---- +phronesis lsp # Starts LSP server (used by editors) +---- + +Added Jason dependency for JSON-RPC: + +[source,elixir] +---- +{:jason, "~> 1.4"} +---- + +[[installation--usage]] +=== Installation & Usage + +==== Build Phronesis + +[source,bash] +---- +cd /path/to/phronesis +mix escript.build +---- + +==== Build VSCode Extension + +[source,bash] +---- +cd editors/vscode +npm install +npm run compile +---- + +==== Install Extension + +[source,bash] +---- +code --install-extension phronesis-0.2.0.vsix +---- + +Or copy to extensions directory: + +[source,bash] +---- +cp -r editors/vscode ~/.vscode/extensions/phronesis-0.2.0/ +---- + +==== Configure VSCode + +Open VSCode settings (Cmd+,) and set: + +[source,json] +---- +{ + "phronesis.serverPath": "/path/to/phronesis" +} +---- + +==== Test LSP Server + +[source,bash] +---- +phronesis lsp # Server starts and waits for JSON-RPC messages +---- + +==== Test Integration + +[source,bash] +---- +mix test test/lsp_integration_test.exs +---- + +=== Examples + +==== Auto-Completion + +Type `Std.` in a `.phr` file: + +.... +Std.RPKI +Std.BGP +Std.Consensus +Std.Temporal +.... + +Type `Std.BGP.`: + +.... +extract_as_path(route) +get_origin(route) +path_length(route) +validate_route(route) +is_private_asn(asn) +.... + +==== Hover Documentation + +Hover over `POLICY`: + +[source,markdown] +---- +**POLICY** + +Define a policy with condition and action + +Syntax: +POLICY : + + +PRIORITY + +Example: +POLICY check_rpki: + IF Std.RPKI.validate(route) == :valid THEN + ACCEPT "RPKI valid" +PRIORITY 100 +---- + +==== Go-to-Definition + +F12 or Cmd+Click on a constant/policy reference jumps to its definition. + +=== LSP Capabilities + +Per LSP spec, the server advertises: + +[source,json] +---- +{ + "capabilities": { + "textDocumentSync": 2, // Incremental sync + "completionProvider": { + "resolveProvider": false, + "triggerCharacters": ["."] + }, + "hoverProvider": true, + "definitionProvider": true, + "documentFormattingProvider": true + } +} +---- + +=== Performance + +* *Startup time:* <1 second +* *Completion latency:* <10ms +* *Hover latency:* <5ms +* *Diagnostics:* Real-time on document change + +=== Status of Follow-on Tooling + +The items that were "next" at the time of the LSP work have since landed: + +[arabic] +. *Debugger* — IMPLEMENTED (`lib/phronesis/debugger.ex` + `debugger/repl.ex`) +. *Profiler* — IMPLEMENTED (`lib/phronesis/profiler.ex` + `profiler/reporter.ex`) +. *Documentation Generator* — IMPLEMENTED (`lib/phronesis/doc_generator.ex`) +. *Package Manager* — IMPLEMENTED (`lib/phronesis/package_manager/`) +. *REPL Enhancements* — partial (interactive REPL via the debugger) + +Newer work: the *reflexion* design layer (`lib/phronesis/reflexion/`) — see `docs/REFLEXION.adoc`. + +=== Commits + +[arabic] +. `c6c8bb3` - feat: implement LSP server and VSCode extension +. `2e1d3c4` - chore: update STATE.scm with LSP completion (60%) + +=== Metrics + +* *Overall Completion:* ~80% (LSP, debugger, profiler, doc-generator, package manager, reflexion all landed) +* *Files Added:* 18 +* *Lines Added:* 2,162 +* *Tests:* 10/10 passing +* *Compilation Warnings:* 12 (minor, non-blocking) + +=== Success Criteria + +✅ LSP server starts and responds to messages +✅ VSCode extension installs and activates +✅ Auto-completion works for keywords and stdlib +✅ Hover documentation displays correctly +✅ Go-to-definition navigates to declarations +✅ Real-time diagnostics show syntax errors +✅ All integration tests pass +✅ Documentation is complete and clear + +=== Credits + +*Author:* Jonathan D.A. Jewell j.d.a.jewell@open.ac.uk +*Co-Authored-By:* Claude Sonnet 4.5 noreply@anthropic.com +*License:* MPL-2.0 diff --git a/LSP-IMPLEMENTATION-SUMMARY.md b/LSP-IMPLEMENTATION-SUMMARY.md deleted file mode 100644 index 0188a77..0000000 --- a/LSP-IMPLEMENTATION-SUMMARY.md +++ /dev/null @@ -1,278 +0,0 @@ - -# LSP Implementation Summary - -**Date:** 2026-01-30 -**Status:** ✅ Complete -**Tests:** 10/10 passing -**Lines of Code:** 2,162 added - -## Overview - -Implemented a complete Language Server Protocol (LSP) server for Phronesis, providing full IDE integration with auto-completion, hover documentation, go-to-definition, and real-time diagnostics. Also created a VSCode extension for immediate productivity. - -## Components Implemented - -### 1. LSP Server (1,200+ lines) - -#### Server Core (`lib/phronesis/lsp/server.ex`) -- JSON-RPC 2.0 protocol implementation -- Message loop over stdin/stdout -- Handles LSP methods: - - `initialize` - Server capabilities handshake - - `textDocument/didOpen` - Document opened - - `textDocument/didChange` - Document modified (incremental sync) - - `textDocument/completion` - Auto-completion requests - - `textDocument/hover` - Hover documentation - - `textDocument/definition` - Go-to-definition - - `textDocument/formatting` - Document formatting -- Real-time diagnostics publishing -- Document cache management - -#### TextDocument Manager (`lib/phronesis/lsp/text_document.ex`) -- Document representation with versioning -- Caches parsed AST and tokens -- Word extraction at cursor position -- Line-based text access - -#### Completion Engine (`lib/phronesis/lsp/completion.ex`) -Auto-completion for: -- **Keywords:** POLICY, CONST, IMPORT, IF, THEN, ELSE, ACCEPT, REJECT, etc. -- **Stdlib Modules:** Std.RPKI, Std.BGP, Std.Consensus, Std.Temporal -- **Stdlib Functions:** All module functions with: - - Signature placeholders (snippets) - - Function documentation - - Example usage - -Completion triggers: -- `Std.` → Shows all stdlib modules -- `Std.BGP.` → Shows all BGP functions -- `PO` → Shows POLICY keyword -- General context → Shows all keywords and modules - -#### Hover Provider (`lib/phronesis/lsp/hover.ex`) -Markdown-formatted documentation for: -- Keywords (POLICY, CONST, IMPORT, ACCEPT, REJECT, etc.) -- Stdlib functions (Std.RPKI.validate, Std.BGP.extract_as_path, etc.) -- Syntax and usage examples - -#### Definition Provider (`lib/phronesis/lsp/definition.ex`) -Go-to-definition support for: -- CONST declarations -- POLICY declarations -- Searches across all open documents - -### 2. VSCode Extension - -#### Extension Files -- `package.json` - Extension manifest with configuration -- `src/extension.ts` - LSP client implementation -- `language-configuration.json` - Brackets, comments, indentation -- `syntaxes/phronesis.tmLanguage.json` - Syntax highlighting -- `README.md` - Installation and usage guide -- `.gitignore` - Excludes node_modules and build artifacts - -#### Features -- Auto-starts LSP server when opening `.phr` files -- Auto-completion with Ctrl+Space -- Hover documentation (mouse over keywords/functions) -- Go-to-definition with F12 or Cmd+Click -- Real-time error diagnostics (red squiggles) -- Format document with Shift+Alt+F -- Configurable server path in settings - -#### Configuration -```json -{ - "phronesis.serverPath": "/path/to/phronesis", - "phronesis.trace.server": "off" -} -``` - -### 3. Integration Tests - -Created `test/lsp_integration_test.exs` with 10 tests: - -1. ✅ TextDocument creates document with text -2. ✅ TextDocument gets word at position -3. ✅ Completion returns completions for keywords -4. ✅ Completion returns completions for Std prefix -5. ✅ Completion returns completions in general -6. ✅ Hover returns hover for keywords -7. ✅ Hover handles hover on empty position -8. ✅ Definition attempts to find definitions -9. ✅ Parsing handles valid syntax -10. ✅ Parsing handles invalid syntax - -**Result:** All 10 tests passing ✅ - -### 4. CLI Integration - -Extended `lib/phronesis/cli.ex` with: -```bash -phronesis lsp # Starts LSP server (used by editors) -``` - -Added Jason dependency for JSON-RPC: -```elixir -{:jason, "~> 1.4"} -``` - -## Installation & Usage - -### Build Phronesis -```bash -cd /path/to/phronesis -mix escript.build -``` - -### Build VSCode Extension -```bash -cd editors/vscode -npm install -npm run compile -``` - -### Install Extension -```bash -code --install-extension phronesis-0.2.0.vsix -``` - -Or copy to extensions directory: -```bash -cp -r editors/vscode ~/.vscode/extensions/phronesis-0.2.0/ -``` - -### Configure VSCode -Open VSCode settings (Cmd+,) and set: -```json -{ - "phronesis.serverPath": "/path/to/phronesis" -} -``` - -### Test LSP Server -```bash -phronesis lsp # Server starts and waits for JSON-RPC messages -``` - -### Test Integration -```bash -mix test test/lsp_integration_test.exs -``` - -## Examples - -### Auto-Completion - -Type `Std.` in a `.phr` file: -``` -Std.RPKI -Std.BGP -Std.Consensus -Std.Temporal -``` - -Type `Std.BGP.`: -``` -extract_as_path(route) -get_origin(route) -path_length(route) -validate_route(route) -is_private_asn(asn) -``` - -### Hover Documentation - -Hover over `POLICY`: -```markdown -**POLICY** - -Define a policy with condition and action - -Syntax: -POLICY : - - -PRIORITY - -Example: -POLICY check_rpki: - IF Std.RPKI.validate(route) == :valid THEN - ACCEPT "RPKI valid" -PRIORITY 100 -``` - -### Go-to-Definition - -F12 or Cmd+Click on a constant/policy reference jumps to its definition. - -## LSP Capabilities - -Per LSP spec, the server advertises: - -```json -{ - "capabilities": { - "textDocumentSync": 2, // Incremental sync - "completionProvider": { - "resolveProvider": false, - "triggerCharacters": ["."] - }, - "hoverProvider": true, - "definitionProvider": true, - "documentFormattingProvider": true - } -} -``` - -## Performance - -- **Startup time:** <1 second -- **Completion latency:** <10ms -- **Hover latency:** <5ms -- **Diagnostics:** Real-time on document change - -## Status of Follow-on Tooling - -The items that were "next" at the time of the LSP work have since landed: - -1. **Debugger** — IMPLEMENTED (`lib/phronesis/debugger.ex` + `debugger/repl.ex`) -2. **Profiler** — IMPLEMENTED (`lib/phronesis/profiler.ex` + `profiler/reporter.ex`) -3. **Documentation Generator** — IMPLEMENTED (`lib/phronesis/doc_generator.ex`) -4. **Package Manager** — IMPLEMENTED (`lib/phronesis/package_manager/`) -5. **REPL Enhancements** — partial (interactive REPL via the debugger) - -Newer work: the **reflexion** design layer (`lib/phronesis/reflexion/`) — see `docs/REFLEXION.adoc`. - -## Commits - -1. `c6c8bb3` - feat: implement LSP server and VSCode extension -2. `2e1d3c4` - chore: update STATE.scm with LSP completion (60%) - -## Metrics - -- **Overall Completion:** ~80% (LSP, debugger, profiler, doc-generator, package manager, reflexion all landed) -- **Files Added:** 18 -- **Lines Added:** 2,162 -- **Tests:** 10/10 passing -- **Compilation Warnings:** 12 (minor, non-blocking) - -## Success Criteria - -✅ LSP server starts and responds to messages -✅ VSCode extension installs and activates -✅ Auto-completion works for keywords and stdlib -✅ Hover documentation displays correctly -✅ Go-to-definition navigates to declarations -✅ Real-time diagnostics show syntax errors -✅ All integration tests pass -✅ Documentation is complete and clear - -## Credits - -**Author:** Jonathan D.A. Jewell -**Co-Authored-By:** Claude Sonnet 4.5 -**License:** MPL-2.0 diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..b51ce10 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,39 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// Copyright (c) Jonathan D.A. Jewell + +[[test-requirements--phronesis]] +== Test Requirements — Phronesis + +[[crg-grade-c--achieved-2026-04-04]] +=== CRG Grade: C — ACHIEVED 2026-04-04 + +All CRG C requirements are met: + +[cols=",,",options="header",] +|=== +|Category |File(s) |Status +|Unit tests |`test/lexer_test.exs`, `test/parser_test.exs`, `test/compiler_test.exs`, etc. |PASS +|Smoke tests |`test/phronesis_test.exs` |PASS +|P2P / property-based |`test/property_test.exs` (StreamData, 5 properties) |PASS (2026-04-04) +|E2E / reflexive |`test/e2e_test.exs` (6 full-pipeline tests) |PASS (2026-04-04) +|Aspect tests |`test/fuzz/lexer_fuzz_test.exs`, `test/fuzz/parser_fuzz_test.exs` |PASS +|Contract tests |`test/conformance_test.exs`, `test/type_checker_test.exs` |PASS +|Benchmarks |`bench/bench_lexer.exs`, `bench/bench_parser.exs` (Benchee) |BASELINED +|=== + +=== Notes + +* `stream_data ~> 1.0` added to `mix.exs` `:test` deps for property tests. +* `lib/phronesis/incremental_parser.ex` fixed: `after` reserved word renamed to `after_text`. +* Fuzz tests in `test/fuzz/` serve as aspect tests (panic-freedom, output hygiene). +* Benchmarks are already present via Benchee — run with `mix run bench/bench_lexer.exs`. + +=== Running Tests + +[source,bash] +---- +mix test # all unit + property + E2E tests +mix run bench/bench_lexer.exs # lexer benchmark +mix run bench/bench_parser.exs # parser benchmark +FUZZ_ITERATIONS=100000 mix test test/fuzz/ # fuzz suite +---- diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index a7b0b40..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,35 +0,0 @@ - -# Test Requirements — Phronesis - -## CRG Grade: C — ACHIEVED 2026-04-04 - -All CRG C requirements are met: - -| Category | File(s) | Status | -|----------|---------|--------| -| Unit tests | `test/lexer_test.exs`, `test/parser_test.exs`, `test/compiler_test.exs`, etc. | PASS | -| Smoke tests | `test/phronesis_test.exs` | PASS | -| P2P / property-based | `test/property_test.exs` (StreamData, 5 properties) | PASS (2026-04-04) | -| E2E / reflexive | `test/e2e_test.exs` (6 full-pipeline tests) | PASS (2026-04-04) | -| Aspect tests | `test/fuzz/lexer_fuzz_test.exs`, `test/fuzz/parser_fuzz_test.exs` | PASS | -| Contract tests | `test/conformance_test.exs`, `test/type_checker_test.exs` | PASS | -| Benchmarks | `bench/bench_lexer.exs`, `bench/bench_parser.exs` (Benchee) | BASELINED | - -## Notes - -- `stream_data ~> 1.0` added to `mix.exs` `:test` deps for property tests. -- `lib/phronesis/incremental_parser.ex` fixed: `after` reserved word renamed to `after_text`. -- Fuzz tests in `test/fuzz/` serve as aspect tests (panic-freedom, output hygiene). -- Benchmarks are already present via Benchee — run with `mix run bench/bench_lexer.exs`. - -## Running Tests - -```bash -mix test # all unit + property + E2E tests -mix run bench/bench_lexer.exs # lexer benchmark -mix run bench/bench_parser.exs # parser benchmark -FUZZ_ITERATIONS=100000 mix test test/fuzz/ # fuzz suite -``` diff --git a/TOOLCHAIN-WISHLIST.adoc b/TOOLCHAIN-WISHLIST.adoc new file mode 100644 index 0000000..df581fd --- /dev/null +++ b/TOOLCHAIN-WISHLIST.adoc @@ -0,0 +1,662 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// Copyright (c) Jonathan D.A. Jewell + +== Phronesis Toolchain Wishlist + +=== Missing Components for Production-Grade Language + +*Current Status:* Basic toolchain complete (45% overall) + +*Existing Tools:* ✅ + +* Lexer, Parser, AST +* Compiler (bytecode + optimizer) +* Interpreter (basic + tracing) +* REPL (interactive mode) +* CLI (`phronesis run/parse/check/repl`) +* Formatter (code formatting) +* Linter (policy validation) +* Standard library (Consensus, BGP, RPKI, Temporal) +* Demo/Examples + +''''' + +=== High Priority (Production Essentials) + +[[1-language-server-protocol-lsp-]] +==== 1. Language Server Protocol (LSP) 📡 + +*Impact:* IDE integration, developer experience +*Effort:* 2-3 weeks + +*Features:* + +* Go to definition +* Find references +* Hover documentation +* Auto-completion +* Inline diagnostics (errors/warnings) +* Code actions (quick fixes) +* Rename symbol +* Signature help + +*Implementation:* + +[source,elixir] +---- +# lib/phronesis/lsp/server.ex +defmodule Phronesis.LSP.Server do + # JSON-RPC server + # textDocument/didOpen, didChange, didSave + # textDocument/completion + # textDocument/hover + # textDocument/definition + # textDocument/references + # textDocument/formatting +end +---- + +*Why Critical:* + +* VSCode/Neovim/Emacs integration +* Real-time error checking +* Autocomplete for Std.BGP._, Std.RPKI._, etc. +* Standard for modern languages + +*Deliverable:* `phronesis lsp` command + +''''' + +[[2-debugger-]] +==== 2. Debugger 🐛 + +*Impact:* Policy development, troubleshooting +*Effort:* 1-2 weeks + +*Features:* + +* Breakpoints in policies +* Step-through execution +* Variable inspection +* Watch expressions +* Call stack +* Trace history navigation + +*Implementation:* + +[source,elixir] +---- +# lib/phronesis/debugger.ex +defmodule Phronesis.Debugger do + # Instrument AST with breakpoints + # Step-by-step evaluation + # State inspection at each step + # Integration with existing Trace module +end +---- + +*Why Critical:* + +* Complex policies hard to debug +* Consensus failures need investigation +* Decision traces help but not interactive + +*Deliverable:* `phronesis debug policy.phr` + +''''' + +[[3-testing-framework-]] +==== 3. Testing Framework 🧪 + +*Impact:* Policy reliability, CI/CD +*Effort:* 1 week + +*Features:* + +* Unit tests for policies +* Property-based testing +* Consensus simulation +* Network scenario testing +* Coverage reporting + +*Implementation:* + +[source,elixir] +---- +# lib/phronesis/test_framework.ex +defmodule Phronesis.Test do + defmacro describe_policy(name, do: block) + defmacro it(description, do: block) + defmacro assert_accept(policy, situation) + defmacro assert_reject(policy, situation, reason) + defmacro assert_consensus(policy, agents, threshold) +end +---- + +*Test File Example:* + +[source,phronesis] +---- +# test/bgp_security_test.phr +TEST "BGP Security Policy" { + SCENARIO "RPKI invalid route" { + GIVEN route = {prefix: "192.0.2.0/24", origin: 99999} + EXPECT REJECT("RPKI validation failed") + } + + SCENARIO "Valid route" { + GIVEN route = {prefix: "192.0.2.0/24", origin: 64512} + EXPECT ACCEPT() + } +} +---- + +*Why Critical:* + +* Network policies are safety-critical +* Regression testing essential +* CI/CD integration + +*Deliverable:* `phronesis test` command + +''''' + +[[4-documentation-generator-]] +==== 4. Documentation Generator 📚 + +*Impact:* API docs, onboarding +*Effort:* 1 week + +*Features:* + +* Auto-generate API docs from modules +* Policy documentation extraction +* Stdlib reference +* Examples/tutorials +* HTML/PDF output + +*Implementation:* + +[source,elixir] +---- +# lib/phronesis/doc.ex +defmodule Phronesis.Doc do + # Extract doc comments from policies + # Generate stdlib reference + # Cross-reference policies + # Export to HTML/Markdown +end +---- + +*Doc Comment Syntax:* + +[source,phronesis] +---- +## +# Validates BGP routes against RPKI ROAs. +# +# @param route - BGP route with prefix and origin +# @returns :valid | :invalid | :not_found +# @example +# route = {prefix: "192.0.2.0/24", origin: 64512} +# Std.RPKI.validate(route) // => :valid +## +---- + +*Why Critical:* + +* Stdlib docs needed +* Policy sharing requires documentation +* Onboarding new users + +*Deliverable:* `phronesis doc` command + +''''' + +[[5-profiler--benchmarking-]] +==== 5. Profiler & Benchmarking ⚡ + +*Impact:* Performance optimization +*Effort:* 1 week + +*Features:* + +* Policy execution time +* Module call profiling +* Consensus latency +* Memory usage +* Hotspot detection +* Flame graphs + +*Implementation:* + +[source,elixir] +---- +# lib/phronesis/profiler.ex +defmodule Phronesis.Profiler do + # Instrument evaluation + # Measure time per policy + # Track module call counts + # Memory allocation tracking + # Export flamegraph.svg +end +---- + +*Why Critical:* + +* Goal: 10k policies/sec +* Need to identify bottlenecks +* Consensus overhead measurement + +*Deliverable:* `phronesis profile policy.phr` + +''''' + +=== Medium Priority (Quality of Life) + +[[6-static-analyzer-]] +==== 6. Static Analyzer 🔍 + +*Impact:* Code quality, bug prevention +*Effort:* 1-2 weeks + +*Features Beyond Linter:* + +* Dead code detection +* Unreachable policy branches +* Unused imports +* Constant propagation analysis +* Consensus threshold validation +* Security vulnerability scanning + +*Example Checks:* + +[source,phronesis] +---- +# Warning: Policy 'never_matches' has unreachable condition +POLICY never_matches: + false AND risk > 50 + THEN REJECT() + +# Warning: Unused import +IMPORT Std.Temporal + +# Error: Consensus threshold must be 0.0 to 1.0 +CONST threshold = 1.5 +---- + +*Deliverable:* `phronesis analyze policy.phr` + +''''' + +[[7-package-manager-]] +==== 7. Package Manager 📦 + +*Impact:* Code reuse, ecosystem +*Effort:* 2-3 weeks + +*Features:* + +* Policy library publishing +* Dependency resolution +* Version management +* Standard library versioning +* Local/remote package registry + +*Package Manifest:* + +[source,nickel] +---- +# phronesis.ncl +{ + name = "acme-network-policies", + version = "1.0.0", + dependencies = { + std = "^0.2.0", + acme-common = "^2.1.0" + }, + policies = [ + "bgp_security.phr", + "rpki_validation.phr" + ] +} +---- + +*Commands:* + +[source,bash] +---- +phronesis pkg init +phronesis pkg install acme-common +phronesis pkg publish +phronesis pkg search rpki +---- + +*Deliverable:* `phronesis pkg` subcommand + +''''' + +[[8-syntax-highlighting-definitions-]] +==== 8. Syntax Highlighting Definitions 🎨 + +*Impact:* Editor support +*Effort:* 2-3 days + +*Targets:* + +* VSCode/VSCodium (TextMate grammar) +* Vim/Neovim (vim syntax file) +* Emacs (major mode) +* Sublime Text +* Kate/KWrite +* GitHub/GitLab (linguist) + +*Files to Create:* + +.... +syntax/ +├── phronesis.tmLanguage.json # VSCode/Sublime +├── phronesis.vim # Vim/Neovim +├── phronesis-mode.el # Emacs +└── phronesis.xml # Kate +.... + +*Deliverable:* Editor plugin packages + +''''' + +[[9-error-reporter--diagnostics-]] +==== 9. Error Reporter & Diagnostics 🚨 + +*Impact:* Developer experience +*Effort:* 1 week + +*Features:* + +* Colorized error messages +* Source context (line + context) +* Suggestions for fixes +* Error codes (E0001, E0002, etc.) +* Related information +* Help text + +*Example:* + +.... +error[E0042]: undefined variable 'risk_levle' + --> bgp_security.phr:12:3 + | +12 | risk_levle > 50 + | ^^^^^^^^^^ not found in this scope + | +help: a variable with a similar name exists + | +12 | risk_level > 50 + | ~~~~~~~~~~ +.... + +*Deliverable:* Enhanced error messages throughout + +''''' + +[[10-code-completion-engine-]] +==== 10. Code Completion Engine 🔮 + +*Impact:* IDE productivity +*Effort:* 1 week + +*Features:* + +* Module/function suggestions +* Variable name completion +* Snippet expansion +* Context-aware suggestions +* Policy template insertion + +*Completions:* + +.... +Std.RPKI.v| → validate(route) + | validation_status(status) + +POLICY | → POLICY name: + | condition + | THEN action + | PRIORITY: 100 +.... + +*Deliverable:* LSP `textDocument/completion` impl + +''''' + +=== Low Priority (Advanced Features) + +[[11-refactoring-tools-️]] +==== 11. Refactoring Tools ♻️ + +*Impact:* Code maintenance +*Effort:* 2 weeks + +*Features:* + +* Extract policy (from condition) +* Inline constant +* Rename variable/policy (safe) +* Move to module +* Extract module function +* Change signature + +*Deliverable:* LSP code actions + +''''' + +[[12-type-checker-gradual-typing-]] +==== 12. Type Checker (Gradual Typing) 🔢 + +*Impact:* Type safety beyond runtime +*Effort:* 2-3 weeks + +*Current:* Dynamic typing with runtime checks +*Proposed:* Optional type annotations + +[source,phronesis] +---- +# Type annotations (optional) +CONST my_asn: Integer = 64512 + +POLICY typed_example: + (route: Route) => route.origin == my_asn + THEN ACCEPT("Owned AS") + +TYPE Route = { + prefix: String, + origin: Integer, + as_path: List +} +---- + +*Deliverable:* `phronesis typecheck` command + +''''' + +[[13-module-registry--package-repository-️]] +==== 13. Module Registry / Package Repository 🏛️ + +*Impact:* Ecosystem growth +*Effort:* 4-6 weeks (infrastructure + UI) + +*Features:* + +* Web UI (search, browse) +* REST API +* Authentication +* Package versioning +* Download statistics +* Documentation hosting + +*Stack:* + +* Phoenix web framework +* PostgreSQL database +* S3/Spaces for storage +* CloudFlare CDN + +*URL:* `https://policies.phronesis.dev` + +*Deliverable:* Full package registry service + +''''' + +[[14-wasm-target-]] +==== 14. WASM Target 🌐 + +*Impact:* Browser execution +*Effort:* 3-4 weeks + +*Goal:* Compile phronesis → WebAssembly + +*Use Cases:* + +* Policy playground in browser +* Client-side policy evaluation +* Embedded in web apps +* Edge computing (Cloudflare Workers) + +*Implementation:* + +[source,bash] +---- +phronesis compile --target wasm policy.phr -o policy.wasm +---- + +*Deliverable:* WASM backend for compiler + +''''' + +[[15-foreign-function-interface-ffi-]] +==== 15. Foreign Function Interface (FFI) 🔌 + +*Impact:* External integration +*Effort:* 2 weeks + +*Goal:* Call Erlang/Elixir from policies + +[source,phronesis] +---- +# Call Elixir function +EXTERN erlang:crypto.hash(Algorithm, Data) -> Hash + +POLICY hash_check: + erlang:crypto.hash(:sha256, data) == expected_hash + THEN ACCEPT() +---- + +*Why Deferred:* + +* Security concerns (sandbox isolation) +* Capability enforcement needed +* BEAM integration complex + +*Deliverable:* `EXTERN` keyword support + +''''' + +=== Implementation Priority Matrix + +[cols=",,,,",options="header",] +|=== +|Tool |Impact |Effort |Priority |When +|LSP |Very High |High |1 |Phase 4 +|Debugger |High |Medium |2 |Phase 4 +|Testing Framework |Very High |Low |3 |Phase 3 +|Profiler |Medium |Low |4 |Phase 4 +|Doc Generator |Medium |Low |5 |Phase 4 +|Static Analyzer |Medium |Medium |6 |Phase 5 +|Syntax Highlighting |High |Very Low |7 |Phase 3 +|Error Reporter |Medium |Low |8 |Phase 4 +|Package Manager |High |High |9 |Phase 5 +|Code Completion |Medium |Low |10 |Phase 4 (via LSP) +|Refactoring |Low |Medium |11 |Phase 6 +|Type Checker |Medium |High |12 |Phase 6 +|Module Registry |Low |Very High |13 |Phase 7 +|WASM Target |Low |High |14 |Phase 7 +|FFI |Medium |Medium |15 |Phase 6 +|=== + +''''' + +=== Recommended Next Steps + +*Phase 3 (Current):* Consensus Integration + +* Add Raft library +* Multi-node cluster + +*Phase 4 (Next):* Developer Tools + +[arabic] +. *Syntax highlighting* (2-3 days) ← Quick win +. *Testing framework* (1 week) ← Essential +. *LSP server* (2-3 weeks) ← Game changer +. *Debugger* (1-2 weeks) +. *Profiler* (1 week) +. *Doc generator* (1 week) + +*Phase 5:* Quality & Ecosystem + +* Static analyzer +* Package manager +* Error reporter enhancements + +*Phase 6:* Advanced Features + +* Gradual type checker +* Refactoring tools +* FFI (if needed) + +*Phase 7:* Infrastructure + +* Module registry (web service) +* WASM target + +''''' + +=== Estimated Timeline + +*Complete Toolchain (Production-Grade):* 12-16 weeks + +* Phase 3: Consensus (1 week) ✅ In progress +* Phase 4: Dev Tools (6-8 weeks) +* Phase 5: Quality (3-4 weeks) +* Phase 6: Advanced (2-3 weeks) +* Phase 7: Infrastructure (when needed) + +*MVP Toolchain:* 8 weeks (Phases 3-4 only) + +''''' + +=== Community Contributions Welcome + +Lower priority items ideal for contributors: + +* Syntax highlighting definitions +* Editor plugins +* Documentation examples +* Policy libraries +* Testing policies + +High-skill contributions: + +* LSP implementation +* Debugger +* WASM backend +* Type checker + +''''' + +*Current Status:* 45% complete +*With full toolchain:* 100% complete (production-ready language) + +*Maintainer:* Jonathan D.A. Jewell j.d.a.jewell@open.ac.uk +*Date:* 2026-01-30 +*License:* MPL-2.0 diff --git a/TOOLCHAIN-WISHLIST.md b/TOOLCHAIN-WISHLIST.md deleted file mode 100644 index c6b21f6..0000000 --- a/TOOLCHAIN-WISHLIST.md +++ /dev/null @@ -1,574 +0,0 @@ - -# Phronesis Toolchain Wishlist -## Missing Components for Production-Grade Language - -**Current Status:** Basic toolchain complete (45% overall) - -**Existing Tools:** ✅ -- Lexer, Parser, AST -- Compiler (bytecode + optimizer) -- Interpreter (basic + tracing) -- REPL (interactive mode) -- CLI (`phronesis run/parse/check/repl`) -- Formatter (code formatting) -- Linter (policy validation) -- Standard library (Consensus, BGP, RPKI, Temporal) -- Demo/Examples - ---- - -## High Priority (Production Essentials) - -### 1. Language Server Protocol (LSP) 📡 -**Impact:** IDE integration, developer experience -**Effort:** 2-3 weeks - -**Features:** -- Go to definition -- Find references -- Hover documentation -- Auto-completion -- Inline diagnostics (errors/warnings) -- Code actions (quick fixes) -- Rename symbol -- Signature help - -**Implementation:** -```elixir -# lib/phronesis/lsp/server.ex -defmodule Phronesis.LSP.Server do - # JSON-RPC server - # textDocument/didOpen, didChange, didSave - # textDocument/completion - # textDocument/hover - # textDocument/definition - # textDocument/references - # textDocument/formatting -end -``` - -**Why Critical:** -- VSCode/Neovim/Emacs integration -- Real-time error checking -- Autocomplete for Std.BGP.*, Std.RPKI.*, etc. -- Standard for modern languages - -**Deliverable:** `phronesis lsp` command - ---- - -### 2. Debugger 🐛 -**Impact:** Policy development, troubleshooting -**Effort:** 1-2 weeks - -**Features:** -- Breakpoints in policies -- Step-through execution -- Variable inspection -- Watch expressions -- Call stack -- Trace history navigation - -**Implementation:** -```elixir -# lib/phronesis/debugger.ex -defmodule Phronesis.Debugger do - # Instrument AST with breakpoints - # Step-by-step evaluation - # State inspection at each step - # Integration with existing Trace module -end -``` - -**Why Critical:** -- Complex policies hard to debug -- Consensus failures need investigation -- Decision traces help but not interactive - -**Deliverable:** `phronesis debug policy.phr` - ---- - -### 3. Testing Framework 🧪 -**Impact:** Policy reliability, CI/CD -**Effort:** 1 week - -**Features:** -- Unit tests for policies -- Property-based testing -- Consensus simulation -- Network scenario testing -- Coverage reporting - -**Implementation:** -```elixir -# lib/phronesis/test_framework.ex -defmodule Phronesis.Test do - defmacro describe_policy(name, do: block) - defmacro it(description, do: block) - defmacro assert_accept(policy, situation) - defmacro assert_reject(policy, situation, reason) - defmacro assert_consensus(policy, agents, threshold) -end -``` - -**Test File Example:** -```phronesis -# test/bgp_security_test.phr -TEST "BGP Security Policy" { - SCENARIO "RPKI invalid route" { - GIVEN route = {prefix: "192.0.2.0/24", origin: 99999} - EXPECT REJECT("RPKI validation failed") - } - - SCENARIO "Valid route" { - GIVEN route = {prefix: "192.0.2.0/24", origin: 64512} - EXPECT ACCEPT() - } -} -``` - -**Why Critical:** -- Network policies are safety-critical -- Regression testing essential -- CI/CD integration - -**Deliverable:** `phronesis test` command - ---- - -### 4. Documentation Generator 📚 -**Impact:** API docs, onboarding -**Effort:** 1 week - -**Features:** -- Auto-generate API docs from modules -- Policy documentation extraction -- Stdlib reference -- Examples/tutorials -- HTML/PDF output - -**Implementation:** -```elixir -# lib/phronesis/doc.ex -defmodule Phronesis.Doc do - # Extract doc comments from policies - # Generate stdlib reference - # Cross-reference policies - # Export to HTML/Markdown -end -``` - -**Doc Comment Syntax:** -```phronesis -## -# Validates BGP routes against RPKI ROAs. -# -# @param route - BGP route with prefix and origin -# @returns :valid | :invalid | :not_found -# @example -# route = {prefix: "192.0.2.0/24", origin: 64512} -# Std.RPKI.validate(route) // => :valid -## -``` - -**Why Critical:** -- Stdlib docs needed -- Policy sharing requires documentation -- Onboarding new users - -**Deliverable:** `phronesis doc` command - ---- - -### 5. Profiler & Benchmarking ⚡ -**Impact:** Performance optimization -**Effort:** 1 week - -**Features:** -- Policy execution time -- Module call profiling -- Consensus latency -- Memory usage -- Hotspot detection -- Flame graphs - -**Implementation:** -```elixir -# lib/phronesis/profiler.ex -defmodule Phronesis.Profiler do - # Instrument evaluation - # Measure time per policy - # Track module call counts - # Memory allocation tracking - # Export flamegraph.svg -end -``` - -**Why Critical:** -- Goal: 10k policies/sec -- Need to identify bottlenecks -- Consensus overhead measurement - -**Deliverable:** `phronesis profile policy.phr` - ---- - -## Medium Priority (Quality of Life) - -### 6. Static Analyzer 🔍 -**Impact:** Code quality, bug prevention -**Effort:** 1-2 weeks - -**Features Beyond Linter:** -- Dead code detection -- Unreachable policy branches -- Unused imports -- Constant propagation analysis -- Consensus threshold validation -- Security vulnerability scanning - -**Example Checks:** -```phronesis -# Warning: Policy 'never_matches' has unreachable condition -POLICY never_matches: - false AND risk > 50 - THEN REJECT() - -# Warning: Unused import -IMPORT Std.Temporal - -# Error: Consensus threshold must be 0.0 to 1.0 -CONST threshold = 1.5 -``` - -**Deliverable:** `phronesis analyze policy.phr` - ---- - -### 7. Package Manager 📦 -**Impact:** Code reuse, ecosystem -**Effort:** 2-3 weeks - -**Features:** -- Policy library publishing -- Dependency resolution -- Version management -- Standard library versioning -- Local/remote package registry - -**Package Manifest:** -```nickel -# phronesis.ncl -{ - name = "acme-network-policies", - version = "1.0.0", - dependencies = { - std = "^0.2.0", - acme-common = "^2.1.0" - }, - policies = [ - "bgp_security.phr", - "rpki_validation.phr" - ] -} -``` - -**Commands:** -```bash -phronesis pkg init -phronesis pkg install acme-common -phronesis pkg publish -phronesis pkg search rpki -``` - -**Deliverable:** `phronesis pkg` subcommand - ---- - -### 8. Syntax Highlighting Definitions 🎨 -**Impact:** Editor support -**Effort:** 2-3 days - -**Targets:** -- VSCode/VSCodium (TextMate grammar) -- Vim/Neovim (vim syntax file) -- Emacs (major mode) -- Sublime Text -- Kate/KWrite -- GitHub/GitLab (linguist) - -**Files to Create:** -``` -syntax/ -├── phronesis.tmLanguage.json # VSCode/Sublime -├── phronesis.vim # Vim/Neovim -├── phronesis-mode.el # Emacs -└── phronesis.xml # Kate -``` - -**Deliverable:** Editor plugin packages - ---- - -### 9. Error Reporter & Diagnostics 🚨 -**Impact:** Developer experience -**Effort:** 1 week - -**Features:** -- Colorized error messages -- Source context (line + context) -- Suggestions for fixes -- Error codes (E0001, E0002, etc.) -- Related information -- Help text - -**Example:** -``` -error[E0042]: undefined variable 'risk_levle' - --> bgp_security.phr:12:3 - | -12 | risk_levle > 50 - | ^^^^^^^^^^ not found in this scope - | -help: a variable with a similar name exists - | -12 | risk_level > 50 - | ~~~~~~~~~~ -``` - -**Deliverable:** Enhanced error messages throughout - ---- - -### 10. Code Completion Engine 🔮 -**Impact:** IDE productivity -**Effort:** 1 week - -**Features:** -- Module/function suggestions -- Variable name completion -- Snippet expansion -- Context-aware suggestions -- Policy template insertion - -**Completions:** -``` -Std.RPKI.v| → validate(route) - | validation_status(status) - -POLICY | → POLICY name: - | condition - | THEN action - | PRIORITY: 100 -``` - -**Deliverable:** LSP `textDocument/completion` impl - ---- - -## Low Priority (Advanced Features) - -### 11. Refactoring Tools ♻️ -**Impact:** Code maintenance -**Effort:** 2 weeks - -**Features:** -- Extract policy (from condition) -- Inline constant -- Rename variable/policy (safe) -- Move to module -- Extract module function -- Change signature - -**Deliverable:** LSP code actions - ---- - -### 12. Type Checker (Gradual Typing) 🔢 -**Impact:** Type safety beyond runtime -**Effort:** 2-3 weeks - -**Current:** Dynamic typing with runtime checks -**Proposed:** Optional type annotations - -```phronesis -# Type annotations (optional) -CONST my_asn: Integer = 64512 - -POLICY typed_example: - (route: Route) => route.origin == my_asn - THEN ACCEPT("Owned AS") - -TYPE Route = { - prefix: String, - origin: Integer, - as_path: List -} -``` - -**Deliverable:** `phronesis typecheck` command - ---- - -### 13. Module Registry / Package Repository 🏛️ -**Impact:** Ecosystem growth -**Effort:** 4-6 weeks (infrastructure + UI) - -**Features:** -- Web UI (search, browse) -- REST API -- Authentication -- Package versioning -- Download statistics -- Documentation hosting - -**Stack:** -- Phoenix web framework -- PostgreSQL database -- S3/Spaces for storage -- CloudFlare CDN - -**URL:** `https://policies.phronesis.dev` - -**Deliverable:** Full package registry service - ---- - -### 14. WASM Target 🌐 -**Impact:** Browser execution -**Effort:** 3-4 weeks - -**Goal:** Compile phronesis → WebAssembly - -**Use Cases:** -- Policy playground in browser -- Client-side policy evaluation -- Embedded in web apps -- Edge computing (Cloudflare Workers) - -**Implementation:** -```bash -phronesis compile --target wasm policy.phr -o policy.wasm -``` - -**Deliverable:** WASM backend for compiler - ---- - -### 15. Foreign Function Interface (FFI) 🔌 -**Impact:** External integration -**Effort:** 2 weeks - -**Goal:** Call Erlang/Elixir from policies - -```phronesis -# Call Elixir function -EXTERN erlang:crypto.hash(Algorithm, Data) -> Hash - -POLICY hash_check: - erlang:crypto.hash(:sha256, data) == expected_hash - THEN ACCEPT() -``` - -**Why Deferred:** -- Security concerns (sandbox isolation) -- Capability enforcement needed -- BEAM integration complex - -**Deliverable:** `EXTERN` keyword support - ---- - -## Implementation Priority Matrix - -| Tool | Impact | Effort | Priority | When | -|------|--------|--------|----------|------| -| LSP | Very High | High | 1 | Phase 4 | -| Debugger | High | Medium | 2 | Phase 4 | -| Testing Framework | Very High | Low | 3 | Phase 3 | -| Profiler | Medium | Low | 4 | Phase 4 | -| Doc Generator | Medium | Low | 5 | Phase 4 | -| Static Analyzer | Medium | Medium | 6 | Phase 5 | -| Syntax Highlighting | High | Very Low | 7 | Phase 3 | -| Error Reporter | Medium | Low | 8 | Phase 4 | -| Package Manager | High | High | 9 | Phase 5 | -| Code Completion | Medium | Low | 10 | Phase 4 (via LSP) | -| Refactoring | Low | Medium | 11 | Phase 6 | -| Type Checker | Medium | High | 12 | Phase 6 | -| Module Registry | Low | Very High | 13 | Phase 7 | -| WASM Target | Low | High | 14 | Phase 7 | -| FFI | Medium | Medium | 15 | Phase 6 | - ---- - -## Recommended Next Steps - -**Phase 3 (Current):** Consensus Integration -- Add Raft library -- Multi-node cluster - -**Phase 4 (Next):** Developer Tools -1. **Syntax highlighting** (2-3 days) ← Quick win -2. **Testing framework** (1 week) ← Essential -3. **LSP server** (2-3 weeks) ← Game changer -4. **Debugger** (1-2 weeks) -5. **Profiler** (1 week) -6. **Doc generator** (1 week) - -**Phase 5:** Quality & Ecosystem -- Static analyzer -- Package manager -- Error reporter enhancements - -**Phase 6:** Advanced Features -- Gradual type checker -- Refactoring tools -- FFI (if needed) - -**Phase 7:** Infrastructure -- Module registry (web service) -- WASM target - ---- - -## Estimated Timeline - -**Complete Toolchain (Production-Grade):** 12-16 weeks - -- Phase 3: Consensus (1 week) ✅ In progress -- Phase 4: Dev Tools (6-8 weeks) -- Phase 5: Quality (3-4 weeks) -- Phase 6: Advanced (2-3 weeks) -- Phase 7: Infrastructure (when needed) - -**MVP Toolchain:** 8 weeks (Phases 3-4 only) - ---- - -## Community Contributions Welcome - -Lower priority items ideal for contributors: -- Syntax highlighting definitions -- Editor plugins -- Documentation examples -- Policy libraries -- Testing policies - -High-skill contributions: -- LSP implementation -- Debugger -- WASM backend -- Type checker - ---- - -**Current Status:** 45% complete -**With full toolchain:** 100% complete (production-ready language) - -**Maintainer:** Jonathan D.A. Jewell -**Date:** 2026-01-30 -**License:** MPL-2.0 diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 68% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index 4bf0181..fc04da3 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,18 +1,16 @@ - - +// SPDX-License-Identifier: CC-BY-SA-4.0 +// Copyright (c) Jonathan D.A. Jewell -# TOPOLOGY.md — phronesis +[[topologymd--phronesis]] += TOPOLOGY — phronesis -## Purpose +=== Purpose Phronesis is a provably safe language for agentic ethical reasoning, combining symbolic AI with neural adaptability. Built on Elixir/BEAM VM, it formalizes ethical reasoning in autonomous systems with formal logic, provable safety guarantees, and neuro-symbolic integration for value-aligned autonomous agents. -## Module Map +=== Module Map -``` +.... phronesis/ ├── lib/phronesis/ # Reference implementation (Elixir/BEAM): lexer, parser, │ # type checker, interpreter, consensus, LSP, reflexion @@ -24,19 +22,19 @@ phronesis/ ├── bench/ # Performance benchmarking ├── docs/ # AsciiDoc design docs (incl. REFLEXION.adoc) └── .github/workflows/ # CI/CD (hypatia-scan, codeql, etc.) -``` +.... -## Data Flow +=== Data Flow -``` +.... [Ethical Spec] ──► [Parser] ──► [Type Checker] ──► [Symbolic Reasoner] ──► [BEAM Bytecode] ↓ ↓ [Formal Proofs] [Provable Safety Properties] -``` +.... -## Key Components +=== Key Components -- **Symbolic reasoning**: Formalize ethical constraints as first-class language features -- **Neural adaptability**: Integrate learned representations with symbolic logic -- **Provable safety**: All autonomous decisions backed by formal proofs -- **BEAM target**: Run on Erlang/Elixir production infrastructure +* *Symbolic reasoning*: Formalize ethical constraints as first-class language features +* *Neural adaptability*: Integrate learned representations with symbolic logic +* *Provable safety*: All autonomous decisions backed by formal proofs +* *BEAM target*: Run on Erlang/Elixir production infrastructure diff --git a/WOKELANG-FEATURE-COMPARISON.adoc b/WOKELANG-FEATURE-COMPARISON.adoc new file mode 100644 index 0000000..5d397bd --- /dev/null +++ b/WOKELANG-FEATURE-COMPARISON.adoc @@ -0,0 +1,205 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// Copyright (c) Jonathan D.A. Jewell + +== Phronesis vs WokeLang Feature Comparison + +=== Summary + +Comparing the 4 features just implemented in WokeLang with Phronesis current state: + +[cols=",,,",options="header",] +|=== +|Feature |WokeLang Status |Phronesis Status |Work Needed +|*1. Record field access* |✅ Complete (just implemented) |✅ *Already complete* |*NONE* +|*2. Stdlib integration* |✅ Complete (fixed polymorphism) |✅ *Already complete* |*NONE* +|*3. Worker concurrency* |⚠️ Partial (workers run, no value passing) |⚠️ *Not applicable* (decidable language) |*N/A* +|*4. Enhanced error messages* |⚠️ Design only |✅ *Already complete* |*NONE* +|=== + +=== Feature 1: Record Field Access with Dot Notation + +==== WokeLang (Just Implemented) + +* Added `Expr::FieldAccess` and `Expr::RecordLiteral` to AST +* Added parser support for `record.field` syntax +* Added typechecker support (nominal types with type_defs) +* Added interpreter evaluation +* Examples: `examples/28_record_fields.woke`, `examples/29_simple_record.woke` + +==== Phronesis (Already Has) + +* ✅ `AST.field_access/2` defined (ast.ex:165-168) +* ✅ `AST.optional_access/2` defined (ast.ex:175-178) - *even better!* (null-safe `?.` operator) +* ✅ Parser handles both syntaxes (parser.ex:362-419) +* ✅ Interpreter evaluates both (interpreter.ex:175-217) +* ✅ Compiler supports both (compiler.ex:449-456, 617-629) +* ✅ Formatter formats both (formatter.ex:233, 237) +* ✅ Linter handles both (linter.ex:408, 412) + +*Result: Phronesis has MORE than WokeLang - includes optional chaining!* + +=== Feature 2: Full Stdlib Integration with Interpreter + +==== WokeLang (Just Fixed) + +* *Problem:* `instantiate()` function not handling polymorphic types +* *Solution:* Rewrote with HashMap-based memoization +* *Result:* All 96 stdlib functions now work with type inference +* Stdlib modules: aLib (22), Math (14), String (20), Array (15), I/O (8), JSON (2), Time (6), Network (3), Channel (7) + +==== Phronesis (Already Has) + +* ✅ Stdlib modules fully integrated: BGP, RPKI, Consensus, Temporal (19 functions total) +* ✅ `resolve_builtin_module/2` wires all stdlib calls (interpreter.ex:397-480) +* ✅ Module system with IMPORT statements +* ✅ All stdlib functions callable from policies +* Examples: +** `Std.BGP.validate_route(route)` → 6 BGP functions +** `Std.RPKI.validate(route)` → 3 RPKI functions +** `Std.Consensus.vote(action, agents, threshold)` → 2 Consensus functions +** `Std.Temporal.now()` → 8 Temporal functions + +*Result: Phronesis stdlib already fully integrated!* + +[[feature-3-worker-concurrency--message-passing]] +=== Feature 3: Worker Concurrency / Message Passing + +==== WokeLang (Partial) + +* ✅ Workers spawn and execute concurrently in background threads +* ✅ Each worker gets isolated interpreter instance +* ✅ Workers can print and execute independently +* ✅ Channel stdlib exists (7 functions) +* ❌ *Architectural limitation:* `Value` contains `Rc>` which isn't `Send` +* ❌ Cannot pass values from worker back to main thread +* ❌ Cannot share channels between workers and main +* *Future work:* Replace `Rc>` with `Arc>` (major refactor) + +==== Phronesis (Architecturally Inappropriate) + +* *Phronesis is a decidable policy language* - NOT a general-purpose programming language +* *Design principle:* No loops, no recursion, guaranteed termination (SPEC.core.scm) +* *Purpose:* Network policy enforcement with consensus-gated execution +* *Concurrency model:* Policies are stateless evaluations that can run concurrently at the BEAM VM level +* *Consensus ≠ Workers:* `Std.Consensus` is for distributed voting (multiple admins approving actions), NOT concurrent workers +* *Intentionally does NOT have workers* - adding them would break decidability guarantees + +*Conclusion:* Worker concurrency is *NOT applicable* to Phronesis's design. It's architecturally inappropriate for a decidable policy language. + +=== Feature 4: Enhanced Error Messages with Hints + +==== WokeLang (Design Only) + +* Created design pattern with `TypeError::with_hint(message, hint)` +* Documented common error patterns: +** Int/String mismatch → suggest `toString()` +** Int/Float mismatch → explain type difference +** Array/value mismatch → suggest using index +** Function type errors → suggest calling function +* *Not implemented:* Would require updating ~30+ error construction sites +* Example file: `examples/36_error_hints.woke` + +==== Phronesis (Already Has!) + +* ✅ *Full diagnostics system* (diagnostics.ex:1-967+ lines) +* ✅ Error codes (E0001-E9999, W0000-W9999) +* ✅ Colorized error messages with ANSI colors +* ✅ Source context with line numbers and highlighting +* ✅ *Suggestion engine with Levenshtein distance* +* ✅ *'Did you mean' suggestions for typos* (undefined_variable/4) +* ✅ Diagnostic reporter with batching and formatting +* ✅ JSON export for tool integration +* ✅ Integration with lexer, parser, and analyzer +* ✅ CLI `diagnose` command + +*Result: Phronesis has a comprehensive diagnostics system that exceeds WokeLang's design!* + +=== Examples of Phronesis Diagnostics + +From diagnostics.ex: + +[source,elixir] +---- +# Undefined variable with "did you mean" suggestion +def undefined_variable(var_name, file, line, column, opts \\ []) do + location = %{file: file, line: line, column: column} + similar = Keyword.get(opts, :similar) + + suggestion = + if similar do + "Did you mean '#{similar}'?" + else + nil + end + + new("E0042", :error, "undefined variable '#{var_name}'", location, + context: Keyword.get(opts, :context), + suggestion: suggestion, + help: "Variables must be defined before use. Check for typos in variable names." + ) +end +---- + +Features: + +* Error code: E0042 +* Contextual message +* Typo suggestions (Levenshtein distance-based) +* Help text +* Source context display + +=== Conclusion + +Out of 4 features requested: + +* *3 are already complete in Phronesis* (field access, stdlib, diagnostics) +* *1 is not applicable* (worker concurrency - incompatible with decidable language design) + +==== Phronesis is Actually MORE Feature-Complete Than WokeLang + +*Language Features:* + +[arabic] +. ✅ Has optional chaining (`?.`) that WokeLang doesn't have +. ✅ Has comprehensive diagnostics system that WokeLang only designed +. ✅ Has interpolated strings (`"Hello ${name}"`) +. ✅ Has null-safe field access + +*Tooling:* + +* ✅ Full LSP server with auto-completion, hover, go-to-definition +* ✅ Interactive debugger with breakpoints and REPL +* ✅ Performance profiler with HTML/CSV/Markdown reports +* ✅ Documentation generator +* ✅ Static analyzer with security checks +* ✅ Package manager with dependency resolution +* ✅ Comprehensive CLI tool (12+ commands) +* ✅ VSCode extension with full IDE support +* ✅ Syntax highlighting for 4 editors (VSCode, Vim, Emacs, Sublime) + +*WokeLang has NONE of the above tooling.* + +==== Why Worker Concurrency Doesn't Apply + +*WokeLang:* General-purpose programming language + +* Needs concurrency primitives for parallel computation +* Workers are appropriate for general programming tasks + +*Phronesis:* Decidable policy language + +* Designed for network configuration and policy enforcement +* *Guaranteed termination* (no loops, no recursion) +* Stateless policy evaluation (policies are pure functions) +* Concurrency happens at infrastructure level (BEAM VM), not language level +* Consensus voting is NOT worker concurrency (it's distributed approval) + +*Adding workers would:* + +* ❌ Break decidability guarantees +* ❌ Violate language design principles +* ❌ Be architecturally inappropriate + +=== Final Assessment + +*No work needed on Phronesis.* All applicable features from the WokeLang session are already implemented and exceed WokeLang's capabilities. The language is production-ready with comprehensive tooling that WokeLang lacks. diff --git a/WOKELANG-FEATURE-COMPARISON.md b/WOKELANG-FEATURE-COMPARISON.md deleted file mode 100644 index d9310d0..0000000 --- a/WOKELANG-FEATURE-COMPARISON.md +++ /dev/null @@ -1,186 +0,0 @@ - -# Phronesis vs WokeLang Feature Comparison - -## Summary - -Comparing the 4 features just implemented in WokeLang with Phronesis current state: - -| Feature | WokeLang Status | Phronesis Status | Work Needed | -|---------|----------------|------------------|-------------| -| **1. Record field access** | ✅ Complete (just implemented) | ✅ **Already complete** | **NONE** | -| **2. Stdlib integration** | ✅ Complete (fixed polymorphism) | ✅ **Already complete** | **NONE** | -| **3. Worker concurrency** | ⚠️ Partial (workers run, no value passing) | ⚠️ **Not applicable** (decidable language) | **N/A** | -| **4. Enhanced error messages** | ⚠️ Design only | ✅ **Already complete** | **NONE** | - -## Feature 1: Record Field Access with Dot Notation - -### WokeLang (Just Implemented) -- Added `Expr::FieldAccess` and `Expr::RecordLiteral` to AST -- Added parser support for `record.field` syntax -- Added typechecker support (nominal types with type_defs) -- Added interpreter evaluation -- Examples: `examples/28_record_fields.woke`, `examples/29_simple_record.woke` - -### Phronesis (Already Has) -- ✅ `AST.field_access/2` defined (ast.ex:165-168) -- ✅ `AST.optional_access/2` defined (ast.ex:175-178) - **even better!** (null-safe `?.` operator) -- ✅ Parser handles both syntaxes (parser.ex:362-419) -- ✅ Interpreter evaluates both (interpreter.ex:175-217) -- ✅ Compiler supports both (compiler.ex:449-456, 617-629) -- ✅ Formatter formats both (formatter.ex:233, 237) -- ✅ Linter handles both (linter.ex:408, 412) - -**Result: Phronesis has MORE than WokeLang - includes optional chaining!** - -## Feature 2: Full Stdlib Integration with Interpreter - -### WokeLang (Just Fixed) -- **Problem:** `instantiate()` function not handling polymorphic types -- **Solution:** Rewrote with HashMap-based memoization -- **Result:** All 96 stdlib functions now work with type inference -- Stdlib modules: aLib (22), Math (14), String (20), Array (15), I/O (8), JSON (2), Time (6), Network (3), Channel (7) - -### Phronesis (Already Has) -- ✅ Stdlib modules fully integrated: BGP, RPKI, Consensus, Temporal (19 functions total) -- ✅ `resolve_builtin_module/2` wires all stdlib calls (interpreter.ex:397-480) -- ✅ Module system with IMPORT statements -- ✅ All stdlib functions callable from policies -- Examples: - - `Std.BGP.validate_route(route)` → 6 BGP functions - - `Std.RPKI.validate(route)` → 3 RPKI functions - - `Std.Consensus.vote(action, agents, threshold)` → 2 Consensus functions - - `Std.Temporal.now()` → 8 Temporal functions - -**Result: Phronesis stdlib already fully integrated!** - -## Feature 3: Worker Concurrency / Message Passing - -### WokeLang (Partial) -- ✅ Workers spawn and execute concurrently in background threads -- ✅ Each worker gets isolated interpreter instance -- ✅ Workers can print and execute independently -- ✅ Channel stdlib exists (7 functions) -- ❌ **Architectural limitation:** `Value` contains `Rc>` which isn't `Send` -- ❌ Cannot pass values from worker back to main thread -- ❌ Cannot share channels between workers and main -- **Future work:** Replace `Rc>` with `Arc>` (major refactor) - -### Phronesis (Architecturally Inappropriate) -- **Phronesis is a decidable policy language** - NOT a general-purpose programming language -- **Design principle:** No loops, no recursion, guaranteed termination (SPEC.core.scm) -- **Purpose:** Network policy enforcement with consensus-gated execution -- **Concurrency model:** Policies are stateless evaluations that can run concurrently at the BEAM VM level -- **Consensus ≠ Workers:** `Std.Consensus` is for distributed voting (multiple admins approving actions), NOT concurrent workers -- **Intentionally does NOT have workers** - adding them would break decidability guarantees - -**Conclusion:** Worker concurrency is **NOT applicable** to Phronesis's design. It's architecturally inappropriate for a decidable policy language. - -## Feature 4: Enhanced Error Messages with Hints - -### WokeLang (Design Only) -- Created design pattern with `TypeError::with_hint(message, hint)` -- Documented common error patterns: - - Int/String mismatch → suggest `toString()` - - Int/Float mismatch → explain type difference - - Array/value mismatch → suggest using index - - Function type errors → suggest calling function -- **Not implemented:** Would require updating ~30+ error construction sites -- Example file: `examples/36_error_hints.woke` - -### Phronesis (Already Has!) -- ✅ **Full diagnostics system** (diagnostics.ex:1-967+ lines) -- ✅ Error codes (E0001-E9999, W0000-W9999) -- ✅ Colorized error messages with ANSI colors -- ✅ Source context with line numbers and highlighting -- ✅ **Suggestion engine with Levenshtein distance** -- ✅ **'Did you mean' suggestions for typos** (undefined_variable/4) -- ✅ Diagnostic reporter with batching and formatting -- ✅ JSON export for tool integration -- ✅ Integration with lexer, parser, and analyzer -- ✅ CLI `diagnose` command - -**Result: Phronesis has a comprehensive diagnostics system that exceeds WokeLang's design!** - -## Examples of Phronesis Diagnostics - -From diagnostics.ex: - -```elixir -# Undefined variable with "did you mean" suggestion -def undefined_variable(var_name, file, line, column, opts \\ []) do - location = %{file: file, line: line, column: column} - similar = Keyword.get(opts, :similar) - - suggestion = - if similar do - "Did you mean '#{similar}'?" - else - nil - end - - new("E0042", :error, "undefined variable '#{var_name}'", location, - context: Keyword.get(opts, :context), - suggestion: suggestion, - help: "Variables must be defined before use. Check for typos in variable names." - ) -end -``` - -Features: -- Error code: E0042 -- Contextual message -- Typo suggestions (Levenshtein distance-based) -- Help text -- Source context display - -## Conclusion - -Out of 4 features requested: -- **3 are already complete in Phronesis** (field access, stdlib, diagnostics) -- **1 is not applicable** (worker concurrency - incompatible with decidable language design) - -### Phronesis is Actually MORE Feature-Complete Than WokeLang - -**Language Features:** -1. ✅ Has optional chaining (`?.`) that WokeLang doesn't have -2. ✅ Has comprehensive diagnostics system that WokeLang only designed -3. ✅ Has interpolated strings (`"Hello ${name}"`) -4. ✅ Has null-safe field access - -**Tooling:** -- ✅ Full LSP server with auto-completion, hover, go-to-definition -- ✅ Interactive debugger with breakpoints and REPL -- ✅ Performance profiler with HTML/CSV/Markdown reports -- ✅ Documentation generator -- ✅ Static analyzer with security checks -- ✅ Package manager with dependency resolution -- ✅ Comprehensive CLI tool (12+ commands) -- ✅ VSCode extension with full IDE support -- ✅ Syntax highlighting for 4 editors (VSCode, Vim, Emacs, Sublime) - -**WokeLang has NONE of the above tooling.** - -### Why Worker Concurrency Doesn't Apply - -**WokeLang:** General-purpose programming language -- Needs concurrency primitives for parallel computation -- Workers are appropriate for general programming tasks - -**Phronesis:** Decidable policy language -- Designed for network configuration and policy enforcement -- **Guaranteed termination** (no loops, no recursion) -- Stateless policy evaluation (policies are pure functions) -- Concurrency happens at infrastructure level (BEAM VM), not language level -- Consensus voting is NOT worker concurrency (it's distributed approval) - -**Adding workers would:** -- ❌ Break decidability guarantees -- ❌ Violate language design principles -- ❌ Be architecturally inappropriate - -## Final Assessment - -**No work needed on Phronesis.** All applicable features from the WokeLang session are already implemented and exceed WokeLang's capabilities. The language is production-ready with comprehensive tooling that WokeLang lacks. diff --git a/mix.exs b/mix.exs index 6f00619..a5f1b4c 100644 --- a/mix.exs +++ b/mix.exs @@ -5,7 +5,7 @@ defmodule Phronesis.MixProject do use Mix.Project - @version "0.1.0" + @version "0.9.0" @source_url "https://github.com/hyperpolymath/phronesis" def project do