Merge pull request #1 from hyperpolymath/claude/phronesis-network-grammar-BQTIM

Phronesis core grammar network configuration

Author: hyperpolymath

.formatter.exs

@@ -0,0 +1,4 @@
+# Used by "mix format"
+[
+  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"]
+]

lib/phronesis.ex

@@ -0,0 +1,115 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-FileCopyrightText: 2025 Phronesis Contributors
+
+defmodule Phronesis do
+  @moduledoc """
+  Phronesis: A Policy Language for Network Configuration.
+
+  A minimal, decidable DSL for expressing network policies with:
+  - Consensus-gated execution
+  - Formal verification guarantees
+  - Modular standard library
+
+  ## Grammar Overview
+
+  The core grammar is ~40 lines of EBNF with 15 keywords:
+
+      POLICY <name>:
+        <condition>
+        THEN <action>
+        PRIORITY: <int>
+        EXPIRES: <datetime> | never
+        CREATED_BY: <identifier>
+
+  ## Quick Start
+
+      # Parse and execute a policy
+      {:ok, ast} = Phronesis.parse(\"""
+        POLICY block_invalid_routes:
+          Std.RPKI.validate(route) == "invalid"
+          THEN REJECT("Invalid RPKI")
+          PRIORITY: 100
+          EXPIRES: never
+          CREATED_BY: security
+      \""")
+
+      {:ok, result} = Phronesis.execute(ast, environment)
+
+  ## Design Principles
+
+  - **Simple Syntax, Powerful Modules**: Core language is minimal;
+    power comes from the Std.* module library
+  - **Decidable**: No loops, guaranteed termination
+  - **Consensus-Safe**: Actions require distributed agreement
+  - **Auditable**: All executions logged immutably
+  """
+
+  alias Phronesis.{Lexer, Parser, Interpreter, State}
+
+  @doc """
+  Parse Phronesis source code into an AST.
+
+  ## Examples
+
+      iex> Phronesis.parse("CONST x = 42")
+      {:ok, [{:const, "x", {:literal, :integer, 42}}]}
+
+      iex> Phronesis.parse("INVALID SYNTAX")
+      {:error, {:parse_error, "expected POLICY, IMPORT, or CONST", 1, 1}}
+  """
+  @spec parse(String.t()) :: {:ok, list()} | {:error, term()}
+  def parse(source) when is_binary(source) do
+    with {:ok, tokens} <- Lexer.tokenize(source),
+         {:ok, ast} <- Parser.parse(tokens) do
+      {:ok, ast}
+    end
+  end
+
+  @doc """
+  Tokenize source code into a list of tokens.
+
+  Useful for debugging the lexer.
+  """
+  @spec tokenize(String.t()) :: {:ok, list()} | {:error, term()}
+  def tokenize(source) when is_binary(source) do
+    Lexer.tokenize(source)
+  end
+
+  @doc """
+  Execute an AST with the given environment and state.
+
+  Returns `{:ok, new_state}` on success, `{:error, reason}` on failure.
+
+  ## Consensus Requirement
+
+  Actions only execute if consensus is achieved (per operational semantics Rule 2).
+  """
+  @spec execute(list(), State.t()) :: {:ok, State.t()} | {:error, term()}
+  def execute(ast, %State{} = state) do
+    Interpreter.execute(ast, state)
+  end
+
+  @doc """
+  Create a new execution state.
+
+  ## Options
+
+  - `:consensus_threshold` - Required vote percentage (default: 0.51)
+  - `:agents` - List of agent IDs for consensus voting
+  """
+  @spec new_state(keyword()) :: State.t()
+  def new_state(opts \\ []) do
+    State.new(opts)
+  end
+
+  @doc """
+  Load and parse a policy file.
+  """
+  @spec load_file(Path.t()) :: {:ok, list()} | {:error, term()}
+  def load_file(path) do
+    case File.read(path) do
+      {:ok, source} -> parse(source)
+      {:error, reason} -> {:error, {:file_error, reason}}
+    end
+  end
+end

lib/phronesis/application.ex

@@ -0,0 +1,19 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-FileCopyrightText: 2025 Phronesis Contributors
+
+defmodule Phronesis.Application do
+  @moduledoc false
+
+  use Application
+
+  @impl true
+  def start(_type, _args) do
+    children = [
+      # Registry for module lookups
+      {Registry, keys: :unique, name: Phronesis.ModuleRegistry}
+    ]
+
+    opts = [strategy: :one_for_one, name: Phronesis.Supervisor]
+    Supervisor.start_link(children, opts)
+  end
+end

lib/phronesis/ast.ex

@@ -0,0 +1,209 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-FileCopyrightText: 2025 Phronesis Contributors
+
+defmodule Phronesis.AST do
+  @moduledoc """
+  Abstract Syntax Tree node definitions for Phronesis.
+
+  The AST follows the grammar specification with these node types:
+
+  ## Top-Level Declarations
+
+  - `{:policy, name, condition, action, metadata}` - Policy declaration
+  - `{:import, module_path, alias}` - Import statement
+  - `{:const, name, expression}` - Constant declaration
+
+  ## Expressions
+
+  - `{:binary_op, op, left, right}` - Binary operations (+, -, *, /, AND, OR)
+  - `{:unary_op, op, operand}` - Unary operations (NOT, -)
+  - `{:comparison, op, left, right}` - Comparisons (==, !=, >, <, etc.)
+  - `{:module_call, path, args}` - Module function call
+  - `{:identifier, name}` - Variable reference
+  - `{:literal, type, value}` - Literal values
+
+  ## Actions
+
+  - `{:execute, function, args}` - Execute action
+  - `{:report, message}` - Report action
+  - `{:reject, reason}` - Reject action
+  - `{:accept, reason}` - Accept action
+  - `{:block, actions}` - Compound action (BEGIN...END)
+  - `{:conditional, condition, then_action, else_action}` - IF/THEN/ELSE
+
+  ## Metadata
+
+  - `%{priority: int, expires: :never | datetime, created_by: identifier}`
+  """
+
+  @type name :: String.t()
+  @type module_path :: [name()]
+
+  @type literal_type :: :integer | :float | :string | :boolean | :ip_address | :datetime
+  @type literal :: {:literal, literal_type(), any()}
+
+  @type comparison_op :: :eq | :neq | :gt | :gte | :lt | :lte | :in
+  @type binary_op :: :add | :sub | :mul | :div | :and | :or
+  @type unary_op :: :not | :neg
+
+  @type expression ::
+          {:binary_op, binary_op(), expression(), expression()}
+          | {:unary_op, unary_op(), expression()}
+          | {:comparison, comparison_op(), expression(), expression()}
+          | {:module_call, module_path(), [expression()]}
+          | {:identifier, name()}
+          | literal()
+
+  @type action ::
+          {:execute, name(), [expression()]}
+          | {:report, expression()}
+          | {:reject, expression() | nil}
+          | {:accept, expression() | nil}
+          | {:block, [action()]}
+          | {:conditional, expression(), action(), action() | nil}
+
+  @type metadata :: %{
+          priority: non_neg_integer(),
+          expires: :never | String.t(),
+          created_by: name() | nil
+        }
+
+  @type policy :: {:policy, name(), expression(), action(), metadata()}
+  @type import_decl :: {:import, module_path(), name() | nil}
+  @type const_decl :: {:const, name(), expression()}
+
+  @type declaration :: policy() | import_decl() | const_decl()
+  @type program :: [declaration()]
+
+  @doc """
+  Create a policy node.
+  """
+  @spec policy(name(), expression(), action(), metadata()) :: policy()
+  def policy(name, condition, action, metadata) do
+    {:policy, name, condition, action, metadata}
+  end
+
+  @doc """
+  Create an import node.
+  """
+  @spec import_decl(module_path(), name() | nil) :: import_decl()
+  def import_decl(path, alias_name \\ nil) do
+    {:import, path, alias_name}
+  end
+
+  @doc """
+  Create a constant declaration node.
+  """
+  @spec const_decl(name(), expression()) :: const_decl()
+  def const_decl(name, value) do
+    {:const, name, value}
+  end
+
+  @doc """
+  Create a binary operation node.
+  """
+  @spec binary_op(binary_op(), expression(), expression()) :: expression()
+  def binary_op(op, left, right) do
+    {:binary_op, op, left, right}
+  end
+
+  @doc """
+  Create a comparison node.
+  """
+  @spec comparison(comparison_op(), expression(), expression()) :: expression()
+  def comparison(op, left, right) do
+    {:comparison, op, left, right}
+  end
+
+  @doc """
+  Create a unary operation node.
+  """
+  @spec unary_op(unary_op(), expression()) :: expression()
+  def unary_op(op, operand) do
+    {:unary_op, op, operand}
+  end
+
+  @doc """
+  Create a module call node.
+  """
+  @spec module_call(module_path(), [expression()]) :: expression()
+  def module_call(path, args) do
+    {:module_call, path, args}
+  end
+
+  @doc """
+  Create an identifier node.
+  """
+  @spec identifier(name()) :: expression()
+  def identifier(name) do
+    {:identifier, name}
+  end
+
+  @doc """
+  Create a literal node.
+  """
+  @spec literal(literal_type(), any()) :: literal()
+  def literal(type, value) do
+    {:literal, type, value}
+  end
+
+  @doc """
+  Create an execute action node.
+  """
+  @spec execute(name(), [expression()]) :: action()
+  def execute(function, args \\ []) do
+    {:execute, function, args}
+  end
+
+  @doc """
+  Create a report action node.
+  """
+  @spec report(expression()) :: action()
+  def report(message) do
+    {:report, message}
+  end
+
+  @doc """
+  Create a reject action node.
+  """
+  @spec reject(expression() | nil) :: action()
+  def reject(reason \\ nil) do
+    {:reject, reason}
+  end
+
+  @doc """
+  Create an accept action node.
+  """
+  @spec accept(expression() | nil) :: action()
+  def accept(reason \\ nil) do
+    {:accept, reason}
+  end
+
+  @doc """
+  Create a block action node.
+  """
+  @spec block([action()]) :: action()
+  def block(actions) do
+    {:block, actions}
+  end
+
+  @doc """
+  Create a conditional action node.
+  """
+  @spec conditional(expression(), action(), action() | nil) :: action()
+  def conditional(condition, then_action, else_action \\ nil) do
+    {:conditional, condition, then_action, else_action}
+  end
+
+  @doc """
+  Create policy metadata.
+  """
+  @spec metadata(keyword()) :: metadata()
+  def metadata(opts \\ []) do
+    %{
+      priority: Keyword.get(opts, :priority, 0),
+      expires: Keyword.get(opts, :expires, :never),
+      created_by: Keyword.get(opts, :created_by)
+    }
+  end
+end