feat: implement Phase 1 deontic constraint engine

Implement the core Phronesis ethical constraint system:

- Manifest: [project], [[constraints]] (obligation/permission/prohibition
  with subject, action, condition, priority), [enforcement] (strict/advisory
  mode, escalation threshold, audit logging), [agent] (name, capabilities)
- Codegen: parser.rs (compile constraints, detect deontic contradictions),
  engine.rs (evaluate actions against constraints with condition predicates),
  audit.rs (structured audit trail with JSON/report output)
- ABI: DeonticModality, Constraint, AgentAction, AuditDecision
  (Permitted/Denied/Escalated), EvaluationResult with reasoning
- 70 tests (31 unit lib + 31 unit bin + 8 integration)
- Example: ai-guardrails/ medical triage bot with 6 constraints

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

Cargo.lock

@@ -18,6 +18,8 @@ anyhow = "1"
 thiserror = "2"
 handlebars = "6"
 walkdir = "2"
+chrono = { version = "0.4", features = ["serde"] }
+serde_json = "1"
 
 [dev-dependencies]
 tempfile = "3"

Cargo.toml

@@ -0,0 +1,40 @@
+= AI Guardrails Example
+// SPDX-License-Identifier: PMPL-1.0-or-later
+
+This example demonstrates a medical triage AI agent with provably safe ethical
+constraints. The `phronesiser.toml` manifest encodes deontic logic rules:
+
+* **Prohibitions**: The bot cannot issue diagnoses or access patient records
+  without consent.
+* **Obligations**: The bot must log every interaction and escalate critical
+  symptoms to a human.
+* **Permissions**: The bot may read public medical guidelines and suggest
+  over-the-counter remedies (when symptoms are not critical).
+
+== Usage
+
+[source,bash]
+----
+# Validate the manifest
+cargo run -- validate -m examples/ai-guardrails/phronesiser.toml
+
+# Generate constraint engine artifacts
+cargo run -- generate -m examples/ai-guardrails/phronesiser.toml -o /tmp/triage-engine
+
+# Show manifest info
+cargo run -- info -m examples/ai-guardrails/phronesiser.toml
+
+# Run self-test
+cargo run -- run -m examples/ai-guardrails/phronesiser.toml
+----
+
+== Constraint Evaluation Rules
+
+The constraint engine evaluates each agent action as follows:
+
+1. Collect all constraints matching the action's `(subject, action)` pair.
+2. Evaluate condition predicates against the action's runtime context.
+3. Apply the highest-priority matching constraint.
+4. In strict mode: prohibitions produce `DENIED` (or `ESCALATED` if
+   `priority >= escalation-threshold`).
+5. Unfulfilled obligations are tracked and reported.

examples/ai-guardrails/README.adoc

@@ -0,0 +1,77 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# phronesiser manifest — AI Guardrails Example
+#
+# This example demonstrates a medical triage AI agent with ethical constraints
+# preventing it from making diagnoses, requiring audit logging, and escalating
+# high-stakes decisions to a human.
+
+[project]
+name = "medical-triage-bot"
+version = "1.0.0"
+description = "Ethical guardrails for an AI-assisted medical triage system"
+
+# Prohibition: the bot must never make a diagnosis directly.
+[[constraints]]
+name = "no-direct-diagnosis"
+kind = "prohibition"
+subject = "agent"
+action = "issue-diagnosis"
+priority = 200
+
+# Prohibition: the bot must not access patient records without consent.
+[[constraints]]
+name = "no-access-without-consent"
+kind = "prohibition"
+subject = "agent"
+action = "access-patient-record"
+condition = "not patient-consent-given"
+priority = 150
+
+# Obligation: the bot must log every interaction for auditability.
+[[constraints]]
+name = "must-log-interaction"
+kind = "obligation"
+subject = "agent"
+action = "write-audit-log"
+priority = 80
+
+# Obligation: the bot must escalate any life-threatening symptom to a human.
+[[constraints]]
+name = "must-escalate-critical"
+kind = "obligation"
+subject = "agent"
+action = "escalate-to-human"
+condition = "symptoms-critical"
+priority = 180
+
+# Permission: the bot may read publicly available medical guidelines.
+[[constraints]]
+name = "can-read-guidelines"
+kind = "permission"
+subject = "agent"
+action = "read-medical-guidelines"
+priority = 10
+
+# Permission: the bot may suggest (not prescribe) over-the-counter remedies.
+[[constraints]]
+name = "can-suggest-otc"
+kind = "permission"
+subject = "agent"
+action = "suggest-otc-remedy"
+condition = "not symptoms-critical"
+priority = 20
+
+[enforcement]
+mode = "strict"
+escalation-threshold = 100
+audit-log = true
+
+[agent]
+name = "triage-assistant"
+capabilities = [
+    "read-medical-guidelines",
+    "suggest-otc-remedy",
+    "write-audit-log",
+    "escalate-to-human",
+    "access-patient-record",
+]

examples/ai-guardrails/phronesiser.toml

@@ -1,3 +1,233 @@
 // SPDX-License-Identifier: PMPL-1.0-or-later
 // Copyright (c) 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
-// ABI module for phronesiser — Idris2 proof types for Phronesis interface correctness.
+//
+// ABI module for phronesiser — Rust-side type definitions mirroring the Idris2
+// formal proofs for Phronesis interface correctness.
+//
+// These types define the core domain model for deontic constraint evaluation:
+// - DeonticModality: The three modalities (obligation, permission, prohibition).
+// - Constraint: A fully resolved constraint ready for evaluation.
+// - AgentAction: An action the agent is attempting to perform.
+// - AuditDecision: The outcome of evaluating an action against constraints.
+// - EvaluationResult: The complete result including decision and reasoning.
+
+use serde::{Deserialize, Serialize};
+use std::fmt;
+
+// ---------------------------------------------------------------------------
+// DeonticModality — the three pillars of deontic logic
+// ---------------------------------------------------------------------------
+
+/// The three fundamental modalities of deontic logic, mirroring the Idris2
+/// ABI definition in `src/interface/abi/Types.idr`.
+///
+/// - `Obligation`: The agent MUST perform the action.
+/// - `Permission`: The agent MAY perform the action.
+/// - `Prohibition`: The agent MUST NOT perform the action.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[repr(u8)]
+pub enum DeonticModality {
+    /// The agent is required to perform the action.
+    Obligation = 0,
+    /// The agent is allowed (but not required) to perform the action.
+    Permission = 1,
+    /// The agent is forbidden from performing the action.
+    Prohibition = 2,
+}
+
+impl fmt::Display for DeonticModality {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            DeonticModality::Obligation => write!(f, "OBLIGATION"),
+            DeonticModality::Permission => write!(f, "PERMISSION"),
+            DeonticModality::Prohibition => write!(f, "PROHIBITION"),
+        }
+    }
+}
+
+impl From<&crate::manifest::ConstraintKind> for DeonticModality {
+    fn from(kind: &crate::manifest::ConstraintKind) -> Self {
+        match kind {
+            crate::manifest::ConstraintKind::Obligation => DeonticModality::Obligation,
+            crate::manifest::ConstraintKind::Permission => DeonticModality::Permission,
+            crate::manifest::ConstraintKind::Prohibition => DeonticModality::Prohibition,
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Constraint — a resolved constraint ready for runtime evaluation
+// ---------------------------------------------------------------------------
+
+/// A fully resolved constraint that the evaluation engine checks at runtime.
+///
+/// This is the ABI-level representation, distinct from the manifest-level
+/// `manifest::Constraint` which is a serialisation format. The ABI constraint
+/// carries a compiled condition predicate.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Constraint {
+    /// Unique identifier for this constraint.
+    pub name: String,
+
+    /// The deontic modality governing this constraint.
+    pub modality: DeonticModality,
+
+    /// The entity the constraint applies to (e.g. "agent", "subsystem").
+    pub subject: String,
+
+    /// The action being constrained (e.g. "delete-records", "send-email").
+    pub action: String,
+
+    /// An optional condition string. When `None`, the constraint applies
+    /// unconditionally. When `Some(pred)`, the constraint only applies
+    /// when `pred` evaluates to true in the current context.
+    pub condition: Option<String>,
+
+    /// Numeric priority for conflict resolution. Higher values win.
+    pub priority: i32,
+}
+
+impl From<&crate::manifest::Constraint> for Constraint {
+    fn from(mc: &crate::manifest::Constraint) -> Self {
+        Constraint {
+            name: mc.name.clone(),
+            modality: DeonticModality::from(&mc.kind),
+            subject: mc.subject.clone(),
+            action: mc.action.clone(),
+            condition: mc.condition.clone(),
+            priority: mc.priority,
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// AgentAction — an action the agent is attempting to perform
+// ---------------------------------------------------------------------------
+
+/// Represents an action that an agent is requesting permission to perform.
+/// The constraint engine evaluates this against all applicable constraints.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AgentAction {
+    /// The agent performing the action.
+    pub agent_name: String,
+
+    /// The action the agent wants to perform (must match constraint `action` fields).
+    pub action: String,
+
+    /// The subject/target of the action (must match constraint `subject` fields).
+    pub subject: String,
+
+    /// Key-value context that condition predicates are evaluated against.
+    /// For example: `{"user-consent-given": "true", "data-classification": "public"}`.
+    pub context: std::collections::HashMap<String, String>,
+}
+
+// ---------------------------------------------------------------------------
+// AuditDecision — the outcome of constraint evaluation
+// ---------------------------------------------------------------------------
+
+/// The decision produced by the constraint engine for a given action.
+///
+/// - `Permitted`: The action is allowed (no prohibitions apply, or an explicit
+///   permission overrides).
+/// - `Denied`: The action violates one or more prohibitions in strict mode.
+/// - `Escalated`: The violated constraint has priority >= the escalation
+///   threshold, requiring human review.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[repr(u8)]
+pub enum AuditDecision {
+    /// The action is permitted to proceed.
+    Permitted = 0,
+    /// The action is denied due to constraint violation.
+    Denied = 1,
+    /// The action requires human escalation before proceeding.
+    Escalated = 2,
+}
+
+impl fmt::Display for AuditDecision {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            AuditDecision::Permitted => write!(f, "PERMITTED"),
+            AuditDecision::Denied => write!(f, "DENIED"),
+            AuditDecision::Escalated => write!(f, "ESCALATED"),
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// EvaluationResult — full evaluation output with reasoning
+// ---------------------------------------------------------------------------
+
+/// The complete result of evaluating an agent action against the constraint set.
+///
+/// Includes the decision, reasoning trail, and references to the constraints
+/// that influenced the outcome.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct EvaluationResult {
+    /// The action that was evaluated.
+    pub action: AgentAction,
+
+    /// The final decision: permitted, denied, or escalated.
+    pub decision: AuditDecision,
+
+    /// Human-readable reasoning explaining why the decision was reached.
+    pub reasoning: Vec<String>,
+
+    /// Names of constraints that applied to this evaluation.
+    pub applicable_constraints: Vec<String>,
+
+    /// Names of constraints that were violated (empty if permitted).
+    pub violated_constraints: Vec<String>,
+
+    /// ISO-8601 timestamp of the evaluation.
+    pub timestamp: String,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_deontic_modality_display() {
+        assert_eq!(DeonticModality::Obligation.to_string(), "OBLIGATION");
+        assert_eq!(DeonticModality::Permission.to_string(), "PERMISSION");
+        assert_eq!(DeonticModality::Prohibition.to_string(), "PROHIBITION");
+    }
+
+    #[test]
+    fn test_audit_decision_display() {
+        assert_eq!(AuditDecision::Permitted.to_string(), "PERMITTED");
+        assert_eq!(AuditDecision::Denied.to_string(), "DENIED");
+        assert_eq!(AuditDecision::Escalated.to_string(), "ESCALATED");
+    }
+
+    #[test]
+    fn test_deontic_modality_repr() {
+        assert_eq!(DeonticModality::Obligation as u8, 0);
+        assert_eq!(DeonticModality::Permission as u8, 1);
+        assert_eq!(DeonticModality::Prohibition as u8, 2);
+    }
+
+    #[test]
+    fn test_audit_decision_repr() {
+        assert_eq!(AuditDecision::Permitted as u8, 0);
+        assert_eq!(AuditDecision::Denied as u8, 1);
+        assert_eq!(AuditDecision::Escalated as u8, 2);
+    }
+
+    #[test]
+    fn test_constraint_from_manifest() {
+        let mc = crate::manifest::Constraint {
+            name: "no-delete".into(),
+            kind: crate::manifest::ConstraintKind::Prohibition,
+            subject: "agent".into(),
+            action: "delete".into(),
+            condition: Some("data-critical".into()),
+            priority: 80,
+        };
+        let c = Constraint::from(&mc);
+        assert_eq!(c.modality, DeonticModality::Prohibition);
+        assert_eq!(c.name, "no-delete");
+        assert_eq!(c.condition, Some("data-critical".into()));
+    }
+}